eliott/authentik
1
0
Fork 0
mirror of https://github.com/goauthentik/authentik synced 2026-04-27 18:07:15 +02:00
Code Issues Packages Projects Releases Wiki Activity

website/docs: Clean up PostgreSQL documentation (#21131)

Browse Source 
* Clean up PostgreSQL documentation

* Overview

* SSL wording

* Conn age

* Schema text

* Replica line

* Direct tip

* Backup text

* Restore text

* Access text

* Copy text

* Issue text

* Sentence case

* Section intro

* Primary reads

* Username text

* Password text

* TLS modes

* Health checks

* Replica case

* Replica intro

* Backup guides

* Docker intro

* Stop stack

* Stop wording

* Backup alt

* Dump wording

* Remove alt

* Network note

* Verify login

* Dump safety

* Log names
This commit is contained in:
Dominic R
2026-04-02 13:37:38 -04:00
committed by GitHub
parent 111f0c072f
commit b96c477b6a
8 changed files with 287 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

161
website/docs/install-config/configuration/configuration.mdx
View File

@@ -63,27 +63,60 @@ To check if your config has been applied correctly, you can run the following co
</Tabs>
## PostgreSQL Settings
## PostgreSQL settings
authentik requires a PostgreSQL database to store its configuration and data. Below are the settings to configure the database connection.
authentik requires PostgreSQL for application data, configuration, sessions, and background task coordination.
Use the settings in this section to configure:
- the primary PostgreSQL connection
- TLS/SSL settings for PostgreSQL
- connection behavior and pooler compatibility
- optional read replicas
For more information, see the PostgreSQL upgrade guides for [Docker Compose](../../troubleshooting/postgres/upgrade_docker.md) and [Kubernetes](../../troubleshooting/postgres/upgrade_kubernetes.md). For backup guidance, see [Backup and restore](../../sys-mgmt/ops/backup-restore.md).
### Connection settings
- `AUTHENTIK_POSTGRESQL__HOST`: Hostname or IP address of your PostgreSQL server.
- `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 for PostgreSQL authentication. If not set, it defaults to the value of the `POSTGRES_PASSWORD` environment variable (this fallback is specific to the default Docker Compose setup).
- `AUTHENTIK_POSTGRESQL__NAME`: The name of the database for authentik to use.
These settings define the primary database connection used for writes and reads, unless you've set up read replicas.
- `AUTHENTIK_POSTGRESQL__HOST`
Hostname or IP address of the PostgreSQL server.
- `AUTHENTIK_POSTGRESQL__PORT`
Port on which PostgreSQL is listening.
Default: `5432`
- `AUTHENTIK_POSTGRESQL__USER`
PostgreSQL username used by authentik to authenticate.
- `AUTHENTIK_POSTGRESQL__PASSWORD`
PostgreSQL password used by authentik to authenticate.
If unset, authentik falls back to `POSTGRES_PASSWORD`. This fallback exists for the default Docker Compose setup and should not be relied on in more complex deployments.
- `AUTHENTIK_POSTGRESQL__NAME`
Name of the PostgreSQL database to use.
:::info Hot-reloading
The `AUTHENTIK_POSTGRESQL__HOST`, `AUTHENTIK_POSTGRESQL__PORT`, `AUTHENTIK_POSTGRESQL__USER`, and `AUTHENTIK_POSTGRESQL__PASSWORD` settings support hot-reloading and can be changed without restarting authentik. However, adding or removing read replicas requires a restart.
:::
### SSL/TLS settings
### TLS/SSL settings
Configure SSL/TLS to secure the connection to your PostgreSQL server.
Use these settings when your PostgreSQL server requires TLS/SSL or mutual TLS.
- `AUTHENTIK_POSTGRESQL__SSLMODE`: Controls the SSL verification mode. Defaults to `verify-ca`.
- `AUTHENTIK_POSTGRESQL__SSLMODE`
Controls how TLS/SSL is used and verified for PostgreSQL connections.
Default: `verify-ca`
- `disable`: No SSL is used.
- `allow`: Use SSL if available, but don't perform verification.
- `prefer`: Attempt an SSL connection first, fall back to non-SSL if it fails.
@@ -91,27 +124,52 @@ Configure SSL/TLS to secure the connection to your PostgreSQL server.
- `verify-ca`: Require SSL and verify that the server certificate is signed by a trusted CA.
- `verify-full`: Require SSL, verify the CA, and verify that the server hostname matches the certificate.
- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`: Path to the CA certificate file for verifying the server's certificate. Required for `verify-ca` and `verify-full` modes.
- `AUTHENTIK_POSTGRESQL__SSLROOTCERT`
- `AUTHENTIK_POSTGRESQL__SSLCERT`: Path to the client SSL certificate file. Required if the PostgreSQL server is configured for mutual TLS and requires client certificates.
Path to the CA certificate file used to verify the PostgreSQL server certificate.
- `AUTHENTIK_POSTGRESQL__SSLKEY`: Path to the private key for the client certificate (`SSLCERT`).
Required for `verify-ca` and `verify-full` modes.
For more details, see [Django's PostgreSQL documentation](https://docs.djangoproject.com/en/stable/ref/databases/#postgresql-connection-settings) or the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION).
- `AUTHENTIK_POSTGRESQL__SSLCERT`
Path to the client certificate file.
Required only if PostgreSQL is configured for mutual TLS and requires client certificates.
- `AUTHENTIK_POSTGRESQL__SSLKEY`
Path to the private key corresponding to `AUTHENTIK_POSTGRESQL__SSLCERT`.
For more detail, see [Django's PostgreSQL documentation](https://docs.djangoproject.com/en/stable/ref/databases/#postgresql-connection-settings) and the [PostgreSQL `libpq` SSL documentation](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION).
### Connection management
These settings control connection persistence and behavior, which is particularly important when using a connection pooler like PgBouncer.
These settings control connection persistence and behavior, which is particularly important when using a connection pooler like PgBouncer or Pgpool.
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`: The maximum age of a database connection in seconds.
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`
Maximum age of a database connection in seconds.
- `0` (default): Connections are closed after each request.
- greater than `0`: Enables persistent connections, with the value defining the maximum lifetime.
- `None`: Unlimited persistence. Use with caution, especially with connection poolers.
See [Django's documentation on persistent connections](https://docs.djangoproject.com/en/stable/ref/databases/#persistent-connections) for more details.
- `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS`: Enables health checks on persistent connections before reuse. Defaults to `false`. This helps prevent errors from stale connections that may have been terminated by the database or a pooler. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks) for details.
In session pool mode, if the pooler drops its backend connection while the client connection remains open, the connection may not be released as expected. See [Django's documentation on persistent connections](https://docs.djangoproject.com/en/stable/ref/databases/#persistent-connections).
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`: Disables server-side cursors. Defaults to `false`. Server-side cursors can improve performance for large result sets but are incompatible with connection poolers in transaction pooling mode (like PgBouncer). **Set this to `true` if you use a transaction-based pooler or encounter cursor-related errors.** See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/databases/#transaction-pooling-and-server-side-cursors) for more details.
- `AUTHENTIK_POSTGRESQL__CONN_HEALTH_CHECKS`
Enables health checks on persistent connections before reuse.
Default: `false`
This helps avoid errors caused by stale connections that were closed by PostgreSQL, a proxy, or a connection pooler. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/settings/#conn-health-checks).
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`
Disables server-side cursors.
Default: `false`
Set this to `true` when using transaction-based pooling, or when you encounter cursor-related errors behind a pooler. Server-side cursors maintain state across queries and are not compatible with transaction pooling. See [Django's documentation](https://docs.djangoproject.com/en/stable/ref/databases/#transaction-pooling-and-server-side-cursors).
### Advanced Settings
@@ -119,22 +177,29 @@ These settings control connection persistence and behavior, which is particularl
The name of the database schema for authentik to use. Defaults to `public`.
This can only be set before authentik is started for the first time. If you specify a custom schema, it must already exist in the database, and the user that authentik connects with must have permissions to access it. The `search_path` for the database user must also be configured to include this schema.
This can only be set before authentik starts for the first time. If you use a custom schema:
- the schema must already exist
- the PostgreSQL user must have permission to use it
- the user's `search_path` must include that schema
- `AUTHENTIK_POSTGRESQL__CONN_OPTIONS`
Arbitrary `libpq` parameter keywords for the database connection. A list of parameter keywords can be found [in the PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
Additional `libpq` connection parameters for the primary database connection.
A list of supported parameter keywords can be found in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
- Parameters passed with this setting will override those passed with other settings.
- These parameters are not applied to read replicas.
- Parameter keywords should be formatted as a base64-encoded JSON dictionary.
- The value must be a base64-encoded JSON dictionary.
### Read Replicas
### Read replicas
You can configure additional read replica databases to distribute database load and improve performance. When read replicas are configured, authentik automatically routes query operations between the primary database (for writes) and read replica databases (for queries). By default, the primary database won't be used for queries when read replicas are available. If you want the primary database to also handle queries, add it as a read replica.
You can configure additional read replica databases to distribute database load and improve performance. When read replicas are configured, authentik automatically routes query operations between the primary database (for writes) and read replica databases (for queries).
To configure authentik to use read replicas, add the settings below to your [configuration file](./configuration.mdx#set-your-environment-variables). If you have multiple read replicas, add settings for each one by using a unique index starting from `0` (e.g., `0`, `1`, `2`, etc.).
By default, the primary database won't be used for queries when read replicas are available. If you want the primary database to also handle queries, add it as a read replica.
The same PostgreSQL settings as described above are used for each read replica. For example, for the first read replica (index `0`):
Each replica uses the same setting structure as the primary connection, but under `READ_REPLICAS`.
For the first replica, use index `0`:
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__HOST`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__NAME`
@@ -150,32 +215,54 @@ The same PostgreSQL settings as described above are used for each read replica.
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__DISABLE_SERVER_SIDE_CURSORS`
- `AUTHENTIK_POSTGRESQL__READ_REPLICAS__0__CONN_OPTIONS`
Additionally, you can set arbitrary connection parameters on all read replicas with:
Use index `1`, `2`, and so on for additional replicas.
- `AUTHENTIK_POSTGRESQL__REPLICA_CONN_OPTIONS`
Arbitrary `libpq` parameter keywords for all read replicas database connections. A list of options can be found [in the PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
Additional `libpq` connection parameters for all read replica connections.
A list of supported keywords can be found in the [PostgreSQL documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS).
- Parameters passed with this setting will override those passed with other settings.
- Parameter keywords should be formatted as a base64-encoded JSON dictionary.
- The value must be a base64-encoded JSON dictionary.
### Using a PostgreSQL Connection Pooler
When your PostgreSQL databases are running behind a connection pooler (like PgBouncer or PgPool), you need to adjust several settings to ensure compatibility:
If authentik connects through a pooler such as PgBouncer or Pgpool, review these settings carefully:
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`:
- `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE`
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 indefinitely.
Session-based pooling can behave poorly with unlimited persistent connections (`null`). If the pooler drops its backend connection while the client connection remains open, the connection may not be released as expected.
To address this incompatibility, either configure the connection pooler to run in transaction pool mode or set this value lower than any timeout that might cause the connection to be dropped (down to `0` to disable persistent connections).
To avoid this, either:
- use transaction pooling, or
- set `CONN_MAX_AGE` lower than the timeout that causes backend connections to be dropped, including `0` to disable persistent connections
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`:
- `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS`
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.
When using transaction pooling, set this to `true`. Server-side cursors keep state across queries and will break when subsequent queries are sent over different backend connections.
### Recommended starting points
These are good starting points for common deployments:
- Direct PostgreSQL connection:
- leave `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE` as `0`
- leave `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS` as `false`
- PgBouncer or Pgpool in transaction mode:
- set `AUTHENTIK_POSTGRESQL__DISABLE_SERVER_SIDE_CURSORS=true`
- keep `AUTHENTIK_POSTGRESQL__CONN_MAX_AGE=0` unless you have a reason to change it
- TLS-secured PostgreSQL:
- keep `AUTHENTIK_POSTGRESQL__SSLMODE=verify-ca` or use `verify-full` if hostname verification is available
### Deprecated Settings
- `AUTHENTIK_POSTGRESQL__USE_PGBOUNCER`: Adjusts the database configuration to support connections to a PgBouncer connection pooler. This setting is 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. This setting is 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_PGBOUNCER`
Deprecated. Use the settings described in [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) instead.
- `AUTHENTIK_POSTGRESQL__USE_PGPOOL`
Deprecated. Use the settings described in [Using a PostgreSQL Connection Pooler](#using-a-postgresql-connection-pooler) instead.
## Cache settings