website/docs: configuration: cleanup postgres section

website/docs/install-config/configuration/configuration.mdx

@@ -65,38 +65,71 @@ To check if your config has been applied correctly, you can run the following co
 
 ## PostgreSQL Settings
 
-- `AUTHENTIK_POSTGRESQL__HOST`: Hostname of your PostgreSQL Server
-- `AUTHENTIK_POSTGRESQL__NAME`: Database name
-- `AUTHENTIK_POSTGRESQL__USER`: Database user
-- `AUTHENTIK_POSTGRESQL__PORT`: Database port, defaults to 5432
-- `AUTHENTIK_POSTGRESQL__PASSWORD`: Database password, defaults to the environment variable `POSTGRES_PASSWORD`
-- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`: Adjust configuration to support connection to PgBouncer. Deprecated, see below
-- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`: Adjust configuration to support connection to Pgpool. Deprecated, see below
-- `AUTHENTIK_POSTGRESQL__SSLMODE`: Strictness of ssl verification. Defaults to `"verify-ca"`
-- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`: CA root for server ssl verification
-- `AUTHENTIK_POSTGRESQL__SSLCERT`: Path to x509 client certificate to authenticate to server
-- `AUTHENTIK_POSTGRESQL__SSLKEY`: Path to private key of `SSLCERT` certificate
-- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`: Database connection lifetime. Defaults to `0` (no persistent connections). Can be set to `null` for unlimited persistent connections. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-max-age) for more details.
-- `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS`: Existing persistent database connections will be health checked before they are reused if set to `true`. Defaults to `false`. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks) for more details.
-- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`: Disable server side cursors when set to `true`. Defaults to `false`. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#disable-server-side-cursors) for more details.
-
-The PostgreSQL settings `HOST`, `PORT`, `USER`, and `PASSWORD` support hot-reloading. Adding and removing read replicas doesn't support hot-reloading.
+### Basic Connection Settings
+
+- `AUTHENTIK_POSTGRESQL__HOST`: Hostname or IP address of your PostgreSQL server where authentik will store its data.
+- `AUTHENTIK_POSTGRESQL__PORT`: Port on which PostgreSQL is listening. Defaults to the standard PostgreSQL port `5432`.
+- `AUTHENTIK_POSTGRESQL__USER`: Username that authentik will use to authenticate with PostgreSQL.
+- `AUTHENTIK_POSTGRESQL__PASSWORD`: Password that authentik will use to authenticate with PostgreSQL. If not specified, defaults to the value of the environment variable `POSTGRES_PASSWORD`. Note that this default behavior only applies when using the default Docker Compose configuration.
+- `AUTHENTIK_POSTGRESQL__NAME`: Name of the database that authentik will use within PostgreSQL.
 
 - `AUTHENTIK_POSTGRESQL__DEFAULT_SCHEMA` :ak-version[2024.12]
 
     The name of the schema used by default in the database. Defaults to `public`.
 
     It is only supported to change this value before the initial start of authentik.
 
-    When setting this value to any non-standard value, the schema must already exist in the database, and the user authentik connects with must have access to it. Additionally the `search_path` of the authentik database must be set to include this schema.
+    When setting this value to any non-standard value, the schema must already exist in the database, and the user authentik connects with must have access to it. Additionally, the `search_path` of the authentik database must be set to include this schema.
+
+The PostgreSQL settings `AUTHENTIK_POSTGRESQL__HOST`, `AUTHENTIK_POSTGRESQL__PORT`, `AUTHENTIK_POSTGRESQL__USER`, and `AUTHENTIK_POSTGRESQL__PASSWORD` support hot-reloading, which means they can be changed without restarting authentik. However, adding and removing read replicas does not support hot-reloading and requires a restart.
+
+### SSL Configuration
+
+- `AUTHENTIK_POSTGRESQL__SSLMODE`: Controls how strictly SSL certificates are verified when connecting to PostgreSQL. Defaults to `verify-ca`. Possible values include:
+    - `disable`: No SSL is used.
+    - `allow`: Use SSL if available, but don't verify.
+    - `prefer`: Try SSL first, but fall back to non-SSL if that fails.
+    - `require`: Use SSL without certificate verification.
+    - `verify-ca`: Verify that the server certificate is signed by a trusted certificate authority.
+    - `verify-full`: Verify both the server certificate and that the hostname matches.
+
+- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`: Specifies the file path to the Certificate Authority (CA) certificate used to verify the PostgreSQL server's SSL certificate. Required when using `verify-ca` or `verify-full` modes.
+
+- `AUTHENTIK_POSTGRESQL__SSLCERT`: Specifies the file path to the client certificate that authentik will present to the PostgreSQL server for mutual TLS authentication. Only needed if your PostgreSQL server requires client certificate authentication.
+
+- `AUTHENTIK_POSTGRESQL__SSLKEY`: Specifies the file path to the private key corresponding to the client certificate specified in `AUTHENTIK_POSTGRESQL__SSLCERT`. Used to prove authentik's identity to the PostgreSQL server.
+
+    See [Django's PostgreSQL documentation](https://docs.djangoproject.com/en/stable/ref/databases/#postgresql-connection-settings) for more details on these settings.
+
+- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`: Maximum age of a database connection in seconds. Defaults to `0` (close after each request). Set to a positive value to enable connection persistence or `None` for unlimited persistence.
 
-### Read replicas
+    See [Django's documentation on persistent connections](https://docs.djangoproject.com/en/stable/ref/databases/#persistent-connections) for details.
 
-You can configure additional read replica databases that are used only for read operations. To configure authentik to use replicas, add the settings below to your [configuration file](./configuration.mdx#set-your-environment-variables). If you have multiple replicas, add additional settings for each replica, replacing the default `0` with a unique value for each additional replica.
+- `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS`: Enables health checks on persistent database connections before they are reused. Defaults to `false`. Helps prevent the use of stale connections that might have been closed by the server.
 
-If read replicas are configured, the main database is not used for reads. If you'd like the main database to be included for reads, add it as a read replica.
+    See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks) for more details on when to enable this feature. Particularly useful when using a connection pooler to detect and recover from stale connections.
 
-The same PostgreSQL settings as described above are used for each read replica.
+- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`: Disables server-side cursors when set to `true`. Defaults to `false`. Server-side cursors can improve performance for large result sets, but are **not compatible** with:
+    - Connection poolers in transaction pooling mode (such as PgBouncer in transaction pooling mode)
+    - Cross-database queries
+    - Some types of database proxies
+
+    **Set this to `true` if you're using PgBouncer in transaction pooling mode or experiencing cursor-related errors.**
+
+    See [Django's documentation on transaction pooling and server-side cursors](https://docs.djangoproject.com/en/stable/ref/databases/#transaction-pooling-and-server-side-cursors) for more details.
+
+### Deprecated Settings
+
+- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`: Adjusts the database configuration to support connections to a PgBouncer connection pooler. Deprecated and will be removed in a future version. Instead, use the configuration described in the [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) section.
+- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`: Adjusts the database configuration to support connections to a Pgpool connection pooler. Deprecated and will be removed in a future version. Instead, use the configuration described in the [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) section.
+
+### Read Replicas
+
+You can configure additional replica databases to distribute database load and improve performance. When replicas are configured, authentik automatically routes query operations between the primary database (for writes) and replica databases (for queries). By default, the primary database won't be used for queries when replicas are available. If you want the primary database to also handle queries, simply add it as a replica too.
+
+To configure authentik to use replicas, add the settings below to your [configuration file](./configuration.mdx#set-your-environment-variables). If you have multiple replicas, add settings for each replica by replacing the default `0` with a unique value for each additional replica.
+
+The same PostgreSQL settings as described above are used for each read replica. For example, for the first replica (index `0`):
 
 - `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__HOST`
 - `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__NAME`
@@ -111,21 +144,19 @@ The same PostgreSQL settings as described above are used for each read replica.
 - `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_HEALTH_CHECKS`
 - `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__DISABLE_SERVER_SIDE_CURSORS`
 
-### Using a PostgreSQL connection pooler (PgBouncer or PgPool)
-
-When your PostgreSQL database(s) are running behind a connection pooler, like PgBouncer or PgPool, two settings need to be overridden:
+### Using a PostgreSQL Connection Pooler
 
-- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`
+When your PostgreSQL databases are running behind a connection pooler (like PgBouncer or PgPool), you need to adjust several settings to ensure compatibility:
 
-    A connection pooler running in session pool mode (PgBouncer default) can be incompatible with unlimited persistent connections enabled by setting this to `null`: If the connection from the connection pooler to the database server is dropped, the connection pooler will wait for the client to disconnect before releasing the connection; however this will **never** happen as authentik is configured to keep the connection to the connection pooler forever.
+- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`:
 
-    To address this incompatibility, either configure the connection pooler to run in transaction pool mode, or update this setting to a value lower than any timeouts that may cause the connection to the database to be dropped (up to `0`).
+    A connection pooler running in session pool mode (which is the default for PgBouncer) can be incompatible with unlimited persistent connections (`null` setting). When the connection from the pooler to the database is dropped, the pooler will wait for the client to disconnect before releasing the connection; however, this will **never** happen as authentik keeps the connection forever.
 
-- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`
+    To address this incompatibility, either configure the connection pooler to run in transaction pool mode, or set this value lower than any timeouts that may cause the connection to be dropped (up to `0` for no persistent connections).
 
-    Using a connection pooler in transaction pool mode (e.g. PgPool, or PgBouncer in transaction or statement pool mode) requires disabling server-side cursors, so this setting must be set to `true`.
+- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`:
 
-Additionally, you can set `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS` to perform health checks on persistent database connections before they are reused.
+    When using a connection pooler in transaction pool mode (e.g., PgPool, or PgBouncer in transaction or statement pool mode), you must set this option to `true`. This is required because server-side cursors maintain state across multiple queries, which is incompatible with transaction-based pooling where connections may change between queries.
 
 ## Redis Settings