Why run authentik on an external PostgreSQL
authentik keeps almost everything in PostgreSQL. The architecture stores all configuration and data in the database except uploaded files, so the database is the system of record for providers, applications, users, flows and audit history. The Kubernetes installation guide makes the same point from the other side: the PostgreSQL bundled with the Helm chart is meant for demonstration and testing, and a separately managed database is recommended for production. If you are moving past a trial, this page is for the team that has to decide where that database lives, how it is secured, and who can back it up, patch it and size it.
The stakes went up in authentik 2025.10. That release removed Redis entirely and moved caching, background tasks, sessions and WebSocket functions onto PostgreSQL, and the release notes warn of roughly 50% more PostgreSQL connections after upgrading. A database that was sized for configuration reads can become the bottleneck for login traffic. Before you cut over, confirm the connection limit of your managed or self-run instance, the connection count authentik will open at your expected user load, and whether a pooler sits between them. Ask your database provider which connection and storage limits apply to the instance class you plan to use.
This page covers the database side of that decision: TLS verification, connection planning, read replicas, poolers and backups. It does not cover installing authentik itself, which is handled on the Docker Compose, Kubernetes and AWS pages, or the internal design of authentik's own high availability setup. Use the authentik high availability documentation as the next read for how replicas and poolers fit into the wider deployment.
Database options and when each fits
This table compares four ways to run the PostgreSQL database behind authentik, from a managed service to an operator-run cluster, and shows who operates each part. Read each row against your team's database skills and your recovery and failover requirements. The main takeaway is that the choice decides who owns failover, backups and connection management, not whether authentik works.
| Option | Ownership split | What your team must operate | Facts that bear on the choice |
|---|---|---|---|
| Managed PostgreSQL service from your cloud provider | Provider runs the server, patching and storage. Your team owns authentik settings, users, roles and TLS configuration. | Instance sizing, parameter settings, connection limits, backup retention and major version upgrades scheduled with the provider. | authentik 2025.10 notes roughly 50% more PostgreSQL connections after upgrading, so confirm the instance connection limit before you size it. |
| Self-run primary with a hot standby | Your team owns the servers, replication, failover decisions and backups. | Streaming replication, a failover runbook, standby monitoring, and manual or scripted promotion. | PostgreSQL hot standbys serve read-only queries, but PostgreSQL does not detect a primary failure or notify the standby, so you need external tooling for automatic failover. |
| Patroni-managed cluster | Your team owns the cluster, its distributed configuration store and the Patroni settings for each deployment. | A distributed configuration store (etcd, Consul, ZooKeeper or Kubernetes), Patroni REST API health checks, switchover drills and version pinning. | Patroni supports PostgreSQL 9.3 to 18 and quorum synchronous commit. Patroni 4.1.5 and 4.0.11 were released August 12, 2026, and older 4.x releases need the memory fix noted in its documentation. |
| CloudNativePG-managed cluster on Kubernetes | Your team owns the Kubernetes cluster, storage classes, operator upgrades and PostgreSQL image choices. The operator handles much of failover. | Kubernetes storage and node capacity, operator version management, backup object storage, and failover tests in your own cluster. | CloudNativePG is an Apache-2.0 CNCF Sandbox operator that fails over through the Kubernetes API server without external tools. Version 1.30.1 was released September 23, 2026. |
| Add a transaction-mode pooler (PgBouncer or Pgpool) | Your team runs the pooler in addition to the database option you chose. | Pooler configuration, health checks, and a separate direct connection for operations that need a stable session. | From authentik 2026.8 a transaction-mode pooler can be used alongside a direct connection. Confirm which session-dependent operations need the direct path. |
| Add read replicas for query offloading | Your team owns replica placement, lag monitoring and routing of read traffic. | Replica lag monitoring, read routing configuration and capacity checks for each replica. | authentik documents read replicas for query offloading. Start with a single primary unless load testing shows reads are the bottleneck. |
How the Redis removal changes connection counts
The 2025.10 release of authentik removed Redis entirely and moved its caching, background tasks, sessions and WebSocket functions onto PostgreSQL. The practical consequence for your database is that every component that used to talk to Redis now opens connections to PostgreSQL instead. The authentik 2025.10 release notes warn of roughly 50% more PostgreSQL connections after upgrading, so a database sized for an older deployment can run out of connection slots shortly after the upgrade. Treat connection capacity as a planned number, not something you discover during an incident.
Before you upgrade, measure your current baseline. Record the number of client connections the database holds at typical peak, using the connection view in your PostgreSQL monitoring or a query against pg_stat_activity, and separate connections by source (the authentik server, the worker, and any other application). Note the current max_connections value and how much headroom remains above peak. Then apply the release notes' warning to that baseline in a staging environment running the same authentik version and load pattern, and confirm the increase against your own numbers rather than assuming the figure applies to your traffic. Ask your database provider or platform team what reserved connections they keep for administration, because those reduce the slots available to authentik.
Use the measured result to decide two settings: max_connections on the database and whether a connection pooler sits between authentik and PostgreSQL. If the projected peak leaves little margin, raising max_connections increases memory use on the server, so a pooler is often the better lever, but pooler mode has consequences that depend on your version. The authentik high availability documentation describes pooler options such as PgBouncer and Pgpool. Re-run the same measurement after the upgrade and again after any scaling of server or worker replicas, since each added replica adds its own connections.
Choosing a PostgreSQL TLS verification mode
When authentik connects to PostgreSQL over a network, each session crosses a path you may not fully control, including load balancers, cloud networking and the endpoint of a managed service. The authentik hardening guide recommends SSL mode verify-ca or verify-full for that case, so the decision is which of the two your environment can support. Encryption without verification is not enough, because an unverified server can still be impersonated.
- Default to verify-full: It validates the certificate chain and the host name, which protects against a server presenting a valid certificate issued for a different host.
- Use verify-ca only with a documented reason: Choose it when the certificate names cannot match the address authentik uses, such as some internal load balancer names, and record the exception for your auditors.
- Avoid require and prefer in production: These modes encrypt traffic but do not verify who answered, so they fall outside the hardening recommendation.
- Ask the provider about its certificates: For a managed service, confirm which certificate authority signs the endpoint certificate and which host names it carries.
After you set the mode, confirm that authentik starts and connects without errors, and that the mode in your connection settings is the one you intended.
Both modes require the client to validate the server certificate against a trusted certificate authority. The difference is the host name check. Verify-ca confirms that the certificate was issued by an authority in the trust store and that it is within its validity period. Verify-full adds a comparison between the address authentik dials and the names listed on the certificate.
- Chain validation (both modes): The server certificate must chain to a certificate authority in the root certificate file that authentik loads.
- Validity period (both modes): An expired or not-yet-valid certificate causes the connection to fail.
- Host name match (verify-full only): The host in the connection settings must match a subject alternative name on the server certificate.
- Failure behavior: A failed check stops the connection. It does not fall back to an unverified link.
Test each mode in a non-production environment using the exact endpoint name that production will use, because a configuration that passes with an IP address can fail on the DNS name.
When authentik and PostgreSQL run on the same host and connect through a Unix domain socket, no network path exists between them for an attacker to intercept. The hardening guide's verify-ca or verify-full recommendation makes an exception for this case, so certificate verification adds little to that link. The protection moves to host access controls and database authentication.
- Socket permissions: Restrict the socket directory and file so that only the authentik service account can connect to it.
- Authentication method: Give the authentik database role a strong server-side method such as SCRAM, and avoid trust entries in the host-based access configuration.
- Same-host assumption: The link stays local only while authentik runs on the database host. If you later move authentik to another machine, the TLS decision returns to the network case.
- Shared hosts: Any other local user, service or container that can reach the socket path can attempt a connection, so review who shares the host.
Before you treat the link as trusted, confirm with your platform team that the socket path is not mounted into any other container or service.
Verification depends on certificate material you supply and keep current. On the authentik side, you provide the certificate authority that signed the PostgreSQL server certificate. On the database side, the server needs its own certificate and private key. If the authentik database role uses certificate authentication, it also needs a client certificate and key.
- CA certificate for authentik: Provide the full chain that authentik should trust, delivered as a file or secret mounted into the authentik containers or pods.
- Server certificate and key on PostgreSQL: The subject or subject alternative names must match the host names authentik uses if you select verify-full.
- Client certificate and key (optional): Needed only when the authentik role uses certificate authentication to log in to the database.
- Rotation plan: Renew certificates before they expire, replace the CA file when the issuing authority changes, and reload or restart the affected services so they load the new files.
Record the owner and expiry date of each file in your certificate inventory, and rehearse a rotation in staging before the first production expiry.
Connecting authentik to an external PostgreSQL
This sequence moves authentik's configuration and data from the bundled database to a PostgreSQL instance you run or manage, with TLS verified at each stage and a confirmed connection budget before go-live.
Provision the database and application roles
Your DBA or platform team creates a dedicated database and a least-privilege login role for authentik on the PostgreSQL instance, sized for the deployment. Confirm the PostgreSQL major version against the supported list in the versioning policy before you start, since version 14 is supported until November 12, 2026. Done means you can log in as the authentik role from a host on the authentik network and create tables in its database, while a connection as a role without that grant is refused.
Configure TLS and certificate trust
Issue or obtain a server certificate for the PostgreSQL endpoint and place the CA certificate where the authentik server and worker containers can read it. Choose the verify-ca or verify-full SSL mode, which the authentik hardening guide recommends unless you use a trusted local socket, and mount the CA file into both containers. Done means a standalone client using the same CA and mode connects without a warning, and a connection with a wrong or missing CA fails.
Point the server and worker at the database
Set the database host, port, name, user, password and SSL mode for both the server and worker containers, keeping the password in a secret store or an environment file that is not committed to version control. Use the same settings for both containers so background tasks and web requests reach the same data. Done means both containers start with the new configuration and their logs show no fallback to the bundled database.
Confirm both containers connect and migrate
Start the server and worker, then watch their logs through the first start, when authentik applies its schema migrations to the new database. Check that the migrations finish without errors and that the administrator login page responds through the reverse proxy. Done means the migration log reports completion in both containers and you can sign in to the admin interface and see the default configuration.
Verify the TLS mode is enforced
On the PostgreSQL side, query the pg_stat_ssl view to confirm that every authentik session is encrypted, and confirm the sslmode value in use matches the one you chose. Then test that a plaintext connection attempt from the authentik host is rejected by the server's pg_hba.conf rules. Done means every authentik backend row reports SSL in use, and the plaintext attempt is refused.
Confirm connection counts under load
Run a representative login and application traffic test while watching the pg_stat_activity count for the authentik role, and compare it with the connection limit on the server. Note that authentik no longer uses Redis and moved caching, tasks, sessions and WebSocket functions to PostgreSQL, and its 2025.10 release notes warn of roughly 50% more PostgreSQL connections after upgrading. Done means peak connections stay below your agreed ceiling with headroom, and you have recorded the number for capacity planning.
Record the backup and restore check
Confirm that your backup method covers the authentik database and that a restore into a separate instance produces a working authentik login. Ask your DBA which backup approach the PostgreSQL platform supports and whether point-in-time recovery is configured. Done means a restore test has completed and the restored instance starts and passes the sign-in check.
Using transaction poolers and read replicas with authentik
authentik supports PostgreSQL read replicas for query offloading and connection poolers such as PgBouncer or Pgpool, so a team can place a pooler between authentik and the database to manage connection counts. The catch is that a transaction-mode pooler hands each transaction to a different server connection, which breaks any operation that relies on session state. From authentik 2026.8, the release notes describe a transaction-mode pooler running alongside a separate direct connection to PostgreSQL for operations that need a stable session. Your team should treat that split as the central design decision for this topic, not a default setting.
Before you route traffic, confirm with the authentik 2026.8 release notes and the authentik high availability documentation exactly which operations go through the pooler and which use the direct path for your target version. Do not assume the mapping carries over from older releases or from a neighboring version. Then test the paths you actually use: sign-in, MFA enrollment, flow execution, outpost connections, background tasks and any blueprint apply. Pay attention to the direct connection's share of the total connection budget, because it counts against the server's limit alongside the pooled connections.
Read replicas need the same kind of check. Confirm which authentik features send reads to a replica and whether any read-after-write sequence, such as creating a user and immediately looking that user up, can hit a replica that has not yet replayed the change. Replication lag is a PostgreSQL behavior, so measure it on your own cluster rather than assuming it is negligible. Keep the pooler, direct path and replica routing in one written configuration reviewed alongside your PostgreSQL version plan, and retest after every authentik or PostgreSQL upgrade.
Backup and recovery planning for the authentik database
A backup plan for authentik has to cover more than the database dump. PostgreSQL holds the configuration and data, but uploaded files live on the server's storage, and a restore is only proven once someone has run one. The cards below cover what to protect, how point-in-time recovery fits, and where failover needs tools that PostgreSQL does not provide.
Scope of the database backup
PostgreSQL stores all authentik configuration and data except uploaded files, so it is the core of any backup. Confirm that your backup job covers the authentik database entirely, including flows, providers, users and events, and that it runs against the instance the server and worker containers actually use. Record which database user and schema the backup targets so a restore lands in the right place.
Uploaded files need their own backup
Icons, backgrounds, uploads and CSV exports are stored outside PostgreSQL, on the local /data volume or in S3-compatible storage if you have moved them. A database restore alone will bring back records that point to files that no longer exist. Back up the file location on the same schedule as the database, and check that the two copies come from the same point in time.
Point-in-time recovery with continuous archiving
Nightly dumps leave a gap of up to a full day. Continuous archiving ships WAL segments to separate storage so you can restore to a chosen moment, for example just before a bad configuration change. Ask your PostgreSQL provider or team whether base backups and WAL archiving are enabled, where the archive is kept, and how long it is retained.
Restore testing
A backup that has never been restored is an assumption. Schedule restores into a separate instance, start authentik against it with a copy of the same configuration, and confirm that sign-in, a sample OIDC or SAML login and the worker can run. Record how long the restore took, because that figure is the recovery time you can actually promise.
Upgrade windows and rollback points
Take a fresh backup immediately before any authentik or PostgreSQL upgrade, since an upgrade changes the schema and a rollback may require restoring the database. Plan the window around the restore time you measured, and keep the previous authentik image available so you can roll back the application if the new version fails after the database is migrated.
Failover needs external tools
PostgreSQL replication can keep a standby current, but PostgreSQL does not detect a failed primary or redirect clients to the standby. Automatic failover needs an external tool such as Patroni or an operator such as CloudNativePG, and the authentik connection string or pooler must point to the new primary. Decide who is paged, how the switch is verified and whether a backup restore remains the fallback.
Questions teams ask before running authentik on external PostgreSQL
What drives the cost of running authentik on external PostgreSQL?
The largest cost driver is whether the database is a managed service or self-run high availability. A managed service moves patching, failover and storage operations to the provider, and you pay that provider directly for instance size, storage, replicas and backups. A self-run cluster adds people and tooling: you need failover software, monitoring, backup storage and staff who can restore from it. Connection pooling, read replicas and backup testing add further work, and each one recurs as long as the system runs. Ask any partner for a quote that separates one-time build work (design, configuration, failover tests, restore drills) from recurring items (database hosting, pooler and monitoring hosting, retainer support). Those are the lines to compare against your own team's time.
How long does an external PostgreSQL setup for authentik take?
Duration depends on scope, not on a fixed template. The main variables are whether a managed service already exists, whether you need high availability with automatic failover, how many environments must match, whether a connection pooler and read replicas are in scope, and how many restore and failover tests your change process requires. Your existing change windows and approval cycles often set the pace as much as the technical work. Ask for a written scope with the environments, test cases and handover steps listed, because those items determine the schedule. Most engagements are fixed-scope, so the timeline is agreed in writing before work starts.
What must our team provide for an external PostgreSQL engagement?
Your team provides access and decisions that only you can make. Typically this includes a database instance or an approved plan for one, network paths from the authentik server and worker hosts, credentials managed in your secrets system, and TLS certificates or the certificate authority that signs them. You also need a maintenance window for the cutover, named owners for database and identity operations, and sign-off on backup retention. Confirm the exact list with your database team before scoping, since access rules and change approvals differ widely between organizations.
Can our own team run authentik on external PostgreSQL without a partner?
Yes, if your team has PostgreSQL operations skills and time to own the setup. The authentik side is configuration of the database connection, TLS verification and connection counts, which is manageable for a platform team. The harder parts are high availability, failover testing, backup restore drills and pooler behavior under load. Teams often underestimate the test effort and the ongoing monitoring. Assess your team's experience with PostgreSQL failover and restore, then decide whether to build internally, bring in a partner for the build, or retain ongoing support.
How do major PostgreSQL upgrades affect authentik?
A major PostgreSQL upgrade changes the on-disk format, so it needs a planned method. PostgreSQL supports dump and restore, pg_upgrade, and logical replication. Logical replication can work between major versions and, per the PostgreSQL documentation, can limit downtime to several seconds, but it still needs careful validation. Check authentik's supported PostgreSQL versions for your authentik release before choosing a target. Also check the connection count, since the 2025.10 release notes warned of higher PostgreSQL connection use after upgrading from Redis-based releases. Rehearse the upgrade on a copy of production data and confirm the pooler mode still works afterward.
What about TLS, backups and restore testing for this setup?
Use certificate verification for the database connection. The authentik hardening guide recommends SSL mode verify-ca or verify-full unless you use a trusted local socket, so plan the certificate chain and hostname checks before go-live. For backups, a successful backup job proves little until a restore has been tested. Define a recovery point target and a recovery time target with your business owners, then run point-in-time recovery drills on a schedule and record the results. Ask any partner to show how restore tests are recorded and who signs off on them.
Does DeployOpen issue a compliance attestation for this work?
No. DeployOpen prepares systems, controls and evidence for compliance assessments, including configuration records, backup and restore test results and access settings. It does not issue audit reports, attestations or certifications. Those come from independent auditors or certification bodies. Confirm early with your auditor which evidence they will accept, and agree in the written scope which evidence DeployOpen will produce.
How DeployOpen scopes external PostgreSQL work
DeployOpen plans, implements, hardens, backs up, documents and supports self-hosted open-source platforms inside the client's own infrastructure, including their cloud accounts, data centers and air-gapped networks. For external PostgreSQL, that means the database work is scoped alongside the authentik deployment itself: which PostgreSQL service runs the database, how the authentik server and worker connect to it, how TLS is verified, how connection counts are sized, and how backups and restore tests are run and recorded. Those decisions depend on your environment, so they are settled in writing before anything is changed.
Most engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts. For this topic, a written scope typically names the PostgreSQL version and hosting model, the connection and pooler design, the TLS mode and certificate chain, the read replica plan if one is needed, the backup and restore verification steps, and the documentation handed over. A quote follows from that written scope, so the more precisely your environment and requirements are described up front, the more closely the quote will match the work. Ask for a quote that lists each deliverable separately so you can see what is one-time and what would recur.
Ongoing support, upgrades and continuous testing are available as a retainer. Database work does not end at go-live: PostgreSQL minor releases, major version planning and authentik upgrades all touch the same connection and backup settings. Confirm with your authentik and PostgreSQL vendors which versions are current for your environment, and agree in the scope who owns each recurring task. DeployOpen does not issue audit reports or certifications for your environment, so any compliance evidence produced here is prepared for your independent assessor.
