update: verify PG password encryption compatibility

.github/vale/styles/config/vocabularies/Aiven/accept.txt

@@ -265,6 +265,7 @@ protoc
 Prometheus
 Protobuf
 Provectus
+proxied
 psql
 Python
 Quix

docs/products/postgresql/concepts/pg-connection-pooling.md

@@ -1,9 +1,14 @@
 ---
-title: Connection pooling
+title: Aiven for PostgreSQL® connection pooling with PgBouncer
+sidebar_label: Connection pooling
 ---
 
+import VerifyPasswordEncryption from "@site/static/includes/pg-password-encryption.md";
+
 Connection pooling in Aiven for PostgreSQL® services allows you to maintain very large numbers of connections to a database while minimizing the consumption of server resources.
 
+<VerifyPasswordEncryption/>
+
 ## About connection pooling
 
 Aiven for PostgreSQL connection pooling uses

docs/products/postgresql/howto/monitor-pgbouncer-with-datadog.md

@@ -1,5 +1,5 @@
 ---
-title: Monitor PgBouncer with Datadog
+title: Monitor PgBouncer with Datadog for Aiven for PostgreSQL®
 sidebar_label: Monitor PgBouncer in Datadog
 ---
 
@@ -58,7 +58,8 @@ avn service integration-create INTEGRATION_CREATE_PARAMETERS \
    --user-config-json '{"datadog_pgbouncer_enabled": true}'
 ```
 
-Replace INTEGRATION_CREATE_PARAMETERS with [the parameters required to create the Datadog Metrics integration](/docs/tools/cli/service/integration#avn_service_integration_create).
+Replace INTEGRATION_CREATE_PARAMETERS with
+[the parameters required to create the Datadog Metrics integration](/docs/tools/cli/service/integration#avn_service_integration_create).
 
 ## Verify the changes
 

docs/products/postgresql/howto/pgbouncer-stats.md

@@ -1,12 +1,16 @@
 ---
-title: Access PgBouncer statistics
+title: Access PgBouncer statistics for Aiven for PostgreSQL®
+sidebar_label: PgBouncer statistics
 ---
 
-import ConsoleIcon from "@site/src/components/ConsoleIcons"
-import ConsoleLabel from "@site/src/components/ConsoleIcons"
+import ConsoleIcon from "@site/src/components/ConsoleIcons";
+import ConsoleLabel from "@site/src/components/ConsoleIcons";
+import VerifyPasswordEncryption from "@site/static/includes/pg-password-encryption.md";
 
 PgBouncer is used at Aiven as a [connection pooler](/docs/products/postgresql/concepts/pg-connection-pooling) to lower the performance impact of opening new connections to Aiven for PostgreSQL®.
 
+<VerifyPasswordEncryption/>
+
 After connecting to PgBouncer, you can display statistics available from PgBouncer, such as:
 
 - `total_xact_count`

docs/products/postgresql/troubleshooting/pg-password-encryption-upgrade.md

@@ -0,0 +1,125 @@
+---
+title: Verify the Aiven for PostgreSQL® password encryption method
+sidebar_label: Verify password encryption
+---
+
+Verify that your Aiven for PostgreSQL® connections use `scram-sha-256` password encryption.
+
+Aiven for PostgreSQL defaults to `scram-sha-256` password encryption for enhanced security,
+moving away from the MD5 method. This new default might need enforcing in specific
+configurations or setups.
+[Check if your action is needed](/docs/products/postgresql/troubleshooting/pg-password-encryption-upgrade#check-if-your-action-is-needed)
+and, if so, update your configuration to enable `scram-sha-256`.
+
+:::important
+PostgreSQL 19 will no longer support the MD5 password encryption, making the
+`scram-sha-256` password encryption mandatory.
+:::
+
+## Check if your action is needed
+
+- **No action is needed** if in your Aiven for PostgreSQL services:
+
+  - There are **no** PgBouncer connection pools tied to specific database users.
+  - All database users are managed by Aiven.
+
+- **Your action is required** if in your Aiven for PostgreSQL services:
+
+  - PgBouncer connection pools are tied to specific database users.
+  - There are database users **not** managed by Aiven.
+
+If your action is required, review the
+[`scram-sha-256` compatibility guidelines](/docs/products/postgresql/troubleshooting/pg-password-encryption-upgrade#scram-sha-256-compatibility-guidelines),
+and follow up, depending on your configuration requirements.
+
+## Ensure scram-sha-256 compatibility
+
+### Ensure app connections to PgBouncer connection pools
+
+When connection pools are configured with specific user names, attempts to connect using
+another role after `scram-sha-256` is enforced fails with a `permission denied` error.
+This is due to the challenge-response authentication flow initiated by the PostgreSQL
+client and proxied by PgBouncer to PostgreSQL.
+
+1. Check which connection pools have specific usernames by running the
+   [`avn service connection-pool-list`](/docs/tools/cli/service/connection-pool) command:
+
+   ```bash
+   avn service connection-pool-list --project PROJECT_NAME SERVICE_NAME
+   ```
+
+   Example output:
+
+   ```text
+   POOL_NAME        DATABASE      USERNAME  POOL_MODE    POOL_SIZE
+   ===============  ============  ========  ===========  =========
+   my_pool          defaultdb     pool_usr  session      20
+   general_pool     defaultdb               transaction  15
+   ```
+
+1. Review the `USERNAME` column to identify potential issues:
+
+   - **Pools with usernames** (`my_pool` with `pool_usr`) may experience authentication
+     issues with `scram-sha-256`.
+   - **Pools without usernames** (`general_pool`) are compatible with `scram-sha-256`.
+
+1. For pools with specific usernames, check your application's connection string
+   `postgresql://pool_usr:password@service-host:port/my_pool` to verify the username
+   matches exactly:
+
+   - Connection string username: `pool_usr`
+   - Pool configuration username: `pool_usr`
+
+1. If the usernames don't match, choose your migration strategy:
+
+   - Remove the username from the pool:
+
+     ```bash
+     avn service connection-pool-update \
+       --project PROJECT_NAME SERVICE_NAME my_pool \
+       --username=""
+     ```
+
+   - [Re-hash the pool user's password](/docs/products/postgresql/troubleshooting/pg-password-encryption-upgrade#re-hash-database-user-passwords).
+
+   - Update your application to use a different compatible pool without specific username
+     requirements:
+
+     ```txt
+     postgresql://any_user:password@service-host:port/general_pool
+     ```
+
+### Update service's `user_config`
+
+Update the password encryption value in your service's `user_config`:
+
+```json
+{
+  "pg": {
+    "password_encryption": "scram-sha-256"
+  }
+}
+```
+
+This enables hashing and authenticating new managed users' passwords using `scram-sha-256`.
+
+:::important
+While this maintains the MD5 compatibility,
+[re-hash the passwords](/docs/products/postgresql/troubleshooting/pg-password-encryption-upgrade#re-hash-database-user-passwords)
+at your earlier convenience.
+:::
+
+### Re-hash database user passwords
+
+Re-hash existing passwords supported by MD5 to use the `scram-sha-256` encryption:
+
+```sql
+ALTER ROLE ROLE_NAME PASSWORD 'ROLE_PASSWORD';
+```
+
+## Troubleshoot connection issues
+
+If you experience authentication failures:
+
+- **Check client library support**: Ensure your PostgreSQL client supports `scram-sha-256`.
+- **Review connection logs**: Look for authentication method mismatches.

docs/products/postgresql/troubleshooting/troubleshooting-connection-pooling.md

@@ -1,10 +1,14 @@
 ---
-title: Troubleshoot connection pooling problems
-sidebar_label: Connection pooling issues
+title: Troubleshoot connection pooling issues in Aiven for PostgreSQL®
+sidebar_label: Pooling issues
 ---
 
+import VerifyPasswordEncryption from "@site/static/includes/pg-password-encryption.md";
+
 Discover the PgBouncer connection pooler and learn how to cope with some specific connection pooling issues.
 
+<VerifyPasswordEncryption/>
+
 ## About connection pooling with PgBouncer
 
 PgBouncer is a lightweight connection pooler for PostgreSQL® with low

sidebars.ts

@@ -1940,6 +1940,7 @@ const sidebars: SidebarsConfig = {
                 'products/postgresql/troubleshooting/troubleshooting-connection-pooling',
                 'products/postgresql/howto/repair-pg-index',
                 'products/postgresql/troubleshooting/troubleshooting-fatal-out-of-shared-mem',
+                'products/postgresql/troubleshooting/pg-password-encryption-upgrade',
               ],
             },
             {

static/includes/pg-password-encryption.md

@@ -0,0 +1,6 @@
+:::note[Verify your password encryption method]
+If you use PGBouncer connection pooling,
+[verify your password encryption method compatibility](/docs/products/postgresql/troubleshooting/pg-password-encryption-upgrade)
+to ensure successful connections. You may need to migrate to `SCRAM-SHA-256` to maintain
+compatibility as the MD5 password encryption will be deprecated in PostgreSQL 19.
+:::