Why an authentik PostgreSQL major upgrade needs its own plan
A PostgreSQL major upgrade moves all authentik configuration and data, so it must be planned as its own change, separate from any authentik application upgrade. If your authentik database runs on PostgreSQL 14, plan now: the supported-versions policy lists November 12, 2026 as the end of support for 14, while 15 runs to November 11, 2027, 16 to November 9, 2028, 17 to November 8, 2029 and 18 to November 14, 2030. Changing base images, a Helm chart version or a managed database service can also force the question, even when the database itself is still supported.
The two changes fail in different ways. An authentik application upgrade changes the code and schema that read the database, while a PostgreSQL major upgrade changes the on-disk format and the server that stores everything, including sessions, tasks and caches since authentik moved those functions into PostgreSQL. Sequence them deliberately: confirm which authentik version you run, confirm it is on a supported release line, and decide whether the database move happens before or after the application step. Do not combine both changes in one maintenance window unless you have rehearsed that exact order. Ask your team to write down the current authentik version, the current PostgreSQL version and the target of each before anything changes.
Your deployment guide determines the work. The authentik Docker Compose upgrade guide uses a logical dump, a stopped stack and a backed-up data directory, while the Kubernetes path is documented separately, and the Helm chart's bundled PostgreSQL is intended for demonstration and test use. If you run a managed or separately operated PostgreSQL cluster, the upgrade is governed by your provider's or DBA's process instead, and you should confirm with them how they handle authentik's connection count and TLS settings before the window.
What changes when PostgreSQL moves to a new major version
This table compares what a minor PostgreSQL update changes with what a major update changes, and which upgrade methods and PostgreSQL 18 details matter for authentik. Read each row as a question to answer before scheduling the upgrade window. Confirm compatibility with the authentik release you run before you change the database.
| Change | Impact on authentik | Action needed |
|---|---|---|
| Minor PostgreSQL release | Never changes the internal storage format, so it only replaces executables and requires a restart of the database. | Apply minor updates in place, then restart the database and confirm authentik reconnects. |
| Major PostgreSQL release | Changes the storage format, so existing data directories cannot be opened by the new major version as they are. | Plan a dump and restore, pg_upgrade, or logical replication before replacing the database. |
| Dump and restore (pg_dumpall) | This is the method authentik's Docker Compose guide uses, with a logical dump taken before the stack is stopped. | Take the dump, stop the stack, back up the existing data directory, then restore and verify before restart. |
| pg_upgrade and logical replication | These are documented alternatives. Confirm with authentik whether its guides support either method for your deployment. | Check the method against your authentik version and your downtime tolerance before choosing. |
| PostgreSQL 18 pg_upgrade changes | Retains planner statistics across major upgrades and adds parallel jobs and a --swap option. | If you target PostgreSQL 18 with pg_upgrade, review these options and test them on a copy first. |
| MD5 password authentication deprecated | PostgreSQL 18 deprecates MD5 in favor of SCRAM, so older password settings may need review. | Confirm which authentication method authentik's connection uses and move users to SCRAM where needed. |
| PostgreSQL 14 end of support | Support for PostgreSQL 14 ends on November 12, 2026, according to the PostgreSQL versioning policy. | Schedule the move to a supported major version before that date, and confirm the target version with your authentik release. |
How the dump, stop, back up and restore path works
The Docker Compose path for a PostgreSQL major upgrade under authentik follows a fixed order, and each step exists to protect the one after it. First, create a logical dump of the existing database while authentik is still running, so you have a version-independent copy of the data. Second, stop the stack so that neither the server container nor the worker container writes to PostgreSQL while the dump and the data directory are being handled. Third, back up the existing PostgreSQL data directory before replacing it, so that a failed restore has a fallback that does not depend on the dump being complete. Only then start the new major version, restore the dump into it, and verify the result before starting authentik again. The authentik upgrade guide for Docker Compose is the document to follow for the exact commands and file paths in your environment.
The verification step matters more than it first appears. PostgreSQL holds all of authentik's configuration and data except uploaded files, including users, applications, providers, flows, policies and sessions. If the restore is incomplete or a table is missing, authentik will not be in a usable state, and it may start and then fail in ways that look like application bugs. Before the worker and server containers start, check that the restore finished without errors, that row counts and key objects match what you recorded before the dump, and that the database answers the connection settings authentik will use. Plan a rollback decision point before this step: if verification fails, you restore the backed up data directory and return to the previous major version rather than debugging live.
Logical replication between PostgreSQL major versions can shorten the outage in principle, because the new server is kept in sync while the old one keeps serving traffic and the cutover takes only seconds. It also adds moving parts: publications and subscriptions must be configured, schema changes and sequence values must be handled, and the team must confirm that authentik's own migrations and tables behave correctly under that setup. Confirm with the authentik guide for your deployment whether the dump and restore path is the documented route for your version and platform before choosing replication. For a single Compose host, the dump path is usually easier to rehearse and reason about, so compare the two on a test copy first.
Preparation before the upgrade window
A PostgreSQL major upgrade is only as safe as the copy you can restore from and the environment you tested it in. The cards below cover the artifacts, inventories and capacity that must exist before anyone stops the authentik stack. Confirm each item with the person who owns the database before the window is scheduled.
Verified backups with a test restore
Take a logical dump of the database and keep a copy of the existing PostgreSQL data directory, since authentik stores all configuration and data in PostgreSQL. A backup counts only after you restore it into a scratch instance and log in to a restored authentik. Record the dump time, the authentik version and the restore result in your change record.
Inventory of PostgreSQL settings
List the PostgreSQL version, server parameters, installed extensions, authentication method and TLS settings that authentik connects with. Compare these against the target major version, since some defaults and deprecated options change between releases. Confirm the list with your database owner before the window opens.
Current authentik version and image tags
Record the exact authentik version running on the server and worker, along with the image tags in your Compose file or the Helm values that pin them. This tells you which upgrade guide applies and which PostgreSQL connection settings the current release expects. Keep the same version identifiers in the runbook so a rollback targets the right images.
Staging environment from production data
Build a staging stack from a recent copy of production data and run the full upgrade there first. Use it to time the dump and restore, find login or application errors and confirm that the rollback steps work. Keep staging on the same network path to PostgreSQL as production so connection and TLS problems show up early.
Capacity for a second instance
Plan room for a second PostgreSQL instance or extra disk to hold the dump and the copied data directory alongside the live data. The Compose guide lists at least 2 CPU cores and 2 GB of RAM as a floor for test setups, not production sizing. The Kubernetes guide recommends a separately managed PostgreSQL for production, so ask your platform team who provisions and pays for that capacity.
Upgrade sequence with checks and rollback points
This sequence moves authentik's PostgreSQL to a new major version in an order where every step has a check that must pass and a preserved copy of the old data to return to until the new database is accepted.
Freeze changes and announce the window
The platform owner announces a maintenance window to the teams that sign in through authentik and to the operators who run it, and freezes configuration changes, provider edits and user imports for the duration. Confirm who can authorize a rollback and who will run the test login. The step is done when the change record names an owner for each action and the freeze has been acknowledged in writing. Until the new database is accepted, the rollback point is the unchanged current environment, which nothing has yet touched.
Confirm authentik and PostgreSQL version compatibility
Check the authentik version you run against the target PostgreSQL major version, using the authentik PostgreSQL upgrade guide for your deployment type (Docker Compose or Kubernetes) and the authentik release notes for the version you run. Confirm the target major version is still within its support window in the PostgreSQL versioning policy. The check passes when the guide and the release notes both name the target as supported. If either is silent, stop and ask the authentik project or your vendor channel before continuing. Nothing has changed yet, so the rollback point is the untouched environment.
Take the logical dump and back up the data directory
Create a logical dump of the authentik database and copy the existing PostgreSQL data directory to a separate, protected location, following the order in the authentik guide. Verify both artifacts: confirm the dump file is non-empty and can be listed or read by the tool that will restore it, and confirm the copied data directory has the expected file tree and size. Record checksums for the copy. The step is done when both copies are readable and stored off the host. These two artifacts are the rollback point until the new database is accepted, and the old data directory must not be reused or modified.
Stop the server and worker containers
Stop the authentik server and worker so that no writes reach PostgreSQL while the dump and backup are finalized and the database is replaced. Confirm that no containers or pods for either component are running and that no background tasks or sessions are still writing. Check the database for active connections from the authentik roles and confirm they have dropped to zero. The step is done when the stack is quiescent. The rollback point is still the dump and the preserved data directory, and restarting the old PostgreSQL with the untouched directory is the fallback if a later step fails.
Start the new PostgreSQL major version
Bring up the new PostgreSQL major version on an empty data directory, as set out in the authentik guide for your platform. Confirm the server accepts connections, the version reported matches the target, and the authentik database role and database exist with the expected settings. On Kubernetes, confirm the chart or managed service points at the new instance and not the old one. The check passes when a client connects to the new instance and reports the target major version. The old data directory is still preserved and untouched, so the rollback point is unchanged.
Restore the dump and run data checks
Restore the logical dump into the new PostgreSQL instance and let the restore finish without errors. Compare row counts for the main authentik tables against the counts recorded from the old database before the freeze, and check that configuration objects such as providers, applications, flows, stages and users are present. Confirm that the authentik version and migration state recorded in the database match what the running version expects. The step is done when counts match and no restore errors remain. If they do not, the rollback point applies: keep the new instance stopped and restart the old database from the preserved data directory.
Start the worker, then the server
Start the authentik worker first so background tasks are ready, then start the server. Watch the startup logs for migration messages, database connection errors and warnings about deprecated settings. Confirm the server reports healthy and that the worker is processing tasks. Check that authentik does not report schema or migration inconsistencies. The step is done when both containers are healthy and the logs show no database errors. If startup fails on the new database, roll back to the old PostgreSQL instance using the preserved data directory and the dump.
Test an OIDC or SAML sign-in and monitor
Sign in as a designated test user, and complete one OIDC or SAML flow against a test application that uses a provider in your configuration. Confirm the token or assertion is issued and the application accepts it. Then monitor server and worker logs and the number of PostgreSQL connections for a period your change plan defines, comparing it to the connection level you recorded before the upgrade. The sequence is complete when the test passes and the connection count is within the limit you set. Keep the dump and the preserved data directory until the team formally accepts the new database, then retire them under your retention policy.
Docker Compose and Kubernetes differ in where the database lives
In a Docker Compose installation, PostgreSQL is usually a service defined in the same stack as the authentik server and worker. The upgrade is therefore a change to the stack itself: the PostgreSQL image tag moves to the new major version, and the data directory that the old server wrote must be handled so the new server can start on it. authentik's Docker Compose upgrade guide creates a logical dump, stops the stack and backs up the existing data directory before replacing it, so the team running the upgrade needs to know exactly where that data lives on the host.
- Image tags: Confirm the PostgreSQL image tag in the compose file and the major version it points to before you change anything.
- Volume paths: Identify the host path or named volume that holds the data directory, and confirm it is the one the running container actually mounts.
- Backup location: Check that the backup of the data directory is written outside the path being replaced and has enough free space.
- Stack shutdown: Plan for authentik to be stopped for the duration of the dump and restore, since no writes can land during the copy.
- Host resources: Confirm the host still meets the documented baseline of at least 2 CPU cores and 2 GB of RAM while both old and new data exist.
Before you begin, check that the compose file is the single source of truth on your host and that no second copy of the stack is running against the same volume.
The authentik Helm chart can install a PostgreSQL instance alongside authentik, but the chart's documentation describes that database as intended for demonstration and test environments. For production, authentik's Kubernetes guidance recommends a separately managed PostgreSQL service. In that model, the database upgrade is governed by the process of whoever runs that service, whether a database platform team, a managed cloud offering or an operator. The authentik side changes mainly through connection settings that point at the upgraded endpoint.
- Bundled or external: Confirm whether your release uses the chart's bundled PostgreSQL or an external database, because the upgrade path differs.
- Owner of the database: Identify which team or provider holds the upgrade procedure, maintenance windows and rollback options.
- Connection settings: Confirm which Helm values or secrets hold the host, port, database name and credentials, and whether TLS is required.
- Version compatibility: Check the PostgreSQL version your authentik release supports before choosing a target major version.
- Rollout order: Confirm whether the database upgrade happens before or after the authentik chart change, and how a failed step is reversed.
For the step-by-step procedure, follow the separate authentik guide for upgrading PostgreSQL on Kubernetes rather than relying on this summary.
Both models share the same risk: PostgreSQL holds all authentik configuration and data, so a failed major upgrade without a verified backup can leave you without a usable identity service. What changes is who holds each step. In a single compose stack, one team usually performs the dump, the stop, the replacement and the restart. In a Kubernetes environment with a separately managed database, the authentik team and the database team need a written handoff that defines who starts the upgrade, who verifies the restored data and who decides on rollback.
- Named owner: Record who approves the start of the upgrade and who can stop it.
- Verification step: Agree on how the restored database is checked before authentik is restarted against it.
- Maintenance window: Confirm the window with the business owners of every application that signs in through authentik.
- Rollback plan: Define the restore source and the steps to return to the previous major version.
- Escalation contact: Name the person to call if the restored data does not match what was backed up.
Before scheduling the change, confirm in writing which team owns each of these items in your environment.
What makes the database upgrade longer or riskier
This table lists the inputs that move the effort and risk of a PostgreSQL major upgrade under authentik, with what to measure for each. Use it to size the change window and to check that your written scope covers the drivers that apply to your environment.
| Driver | Why it matters | What to measure |
|---|---|---|
| Database size | Dump, restore and verification time grow with the amount of data, and the stack stays stopped while the data is copied. | Current on-disk size of the authentik database, row counts for large tables, and a timed test dump and restore in a non-production copy. |
| Bundled or separately managed database | The Helm chart bundles PostgreSQL for demonstration and test use, so a bundled database needs a different path than a managed or dedicated server. | Whether the database runs inside the chart or on a separate server, who owns its backups, and which PostgreSQL version is currently running. |
| Replicas, standbys and failover tooling | Standbys and external failover tools must be rebuilt or reconfigured for the new major version, and PostgreSQL does not detect failure on its own. | Number of standbys, replication mode, the failover tool in use, and whether it is paused and re-enabled during the window. |
| Connection count after the upgrade | The 2025.10 release notes warn of roughly 50% more PostgreSQL connections after upgrading authentik, which can exhaust limits sized for the older release. | Current connection count and max_connections at peak, plus the headroom after a test run on the target authentik version. |
| Connection pooler in front of PostgreSQL | A pooler such as PgBouncer changes how connections are counted and may need its own configuration or a restart during the cutover. | Whether a pooler is present, its pool modes and limits, and whether it points at the same host and port after the upgrade. |
| Custom extensions, roles and settings | Extensions must be available for the target version, and custom roles, authentication methods or server settings may not carry over unchanged. | List of installed extensions, non-default roles and grants, pg_hba rules, and custom postgresql.conf values. |
| Free disk for backup copies | The data directory is backed up before it is replaced and the dump needs its own space, so disk pressure can stop the window. | Free space on the volume holding the data directory and the dump location, compared with the current size of the data. |
| Depth of verification | Checking only that the service starts misses data gaps, and the depth chosen sets how long the window must be. | Agreed checks such as login tests, configuration review, object counts and an application sign-in test before the stack returns to use. |
| Change window agreed with the business | The stack is stopped during the dump and restore, so the window must fit business hours and the rollback plan must be known before it opens. | Approved start and end times, the rollback decision point, who signs off, and how users are told sign-in will be unavailable. |
Questions teams ask before upgrading PostgreSQL under authentik
How much does a PostgreSQL major upgrade under authentik cost?
No fixed figure applies, because the cost follows from the written scope rather than a published rate. Your quote will depend on the deployment type (Docker Compose or Kubernetes), whether PostgreSQL is bundled or separately managed, the size of the database, how many environments need the work (staging and production), how deep the verification goes, and whether your team or a partner performs each step. Ask for the cost to be split into planning, the dump and restore, verification, and any follow-up support, and state which items are one-time and which recur. DeployOpen does not publish a price list, so a quote is based on that written scope.
How long does the upgrade window need to be?
The window is set mainly by how long the logical dump takes to create, how long the restore takes into the new major version, and how long verification takes before authentik restarts. Dump and restore time grows with database size and hardware, so measure it on a staging copy of your own data rather than relying on a generic estimate. Testing time depends on how many integrations, flows and users you need to check. PostgreSQL's upgrade documentation describes logical replication as a route to a major upgrade with only several seconds of downtime, but that route involves more setup than a dump and restore, so confirm which method fits your environment before you schedule a window.
What must our team provide before the work starts?
Expect to provide administrative access to the host or cluster, the PostgreSQL credentials and connection details, and enough storage for the logical dump and the backup of the existing data directory. You will also need a named change approver, a maintenance window agreed with the business, and a staging copy of authentik and its database that matches production as closely as possible. Test users and test accounts for each provider type you rely on, such as OAuth2/OIDC, SAML or LDAP, let you confirm that sign-in still works after the restore. List these inputs in the written scope so that gaps are visible before the change window opens.
Can our in-house team perform the upgrade using the official guides?
Yes, a team with PostgreSQL and container or Kubernetes experience can follow authentik's published guides, which cover Docker Compose and Kubernetes separately. The Compose guide creates a logical dump, stops the stack and backs up the data directory before replacing it. The main risks are skipping the backup, restoring into the wrong major version, or restarting authentik before confirming the data is complete. Decide before starting who owns each step, who signs off on verification, and who can roll back. If your team lacks that depth or capacity, a partner can take on part or all of the work under a written scope.
Do we need to upgrade the authentik application at the same time?
Not necessarily, but you should plan the two changes together because each one changes what the other must support. A PostgreSQL major version change is a database operation, while authentik version upgrades have their own rules, including the sequential upgrade path and per-release breaking changes. Confirm which authentik version you run now and which PostgreSQL versions that release supports before you choose a target. Keeping the change sets separate usually makes failures easier to diagnose, so state in your plan which change happens first and what evidence closes each one.
What happens if verification fails after the restore?
Stop before restarting authentik and do not point users at the new database until the failure is understood. Because the upgrade begins with a logical dump and a backup of the existing data directory, you can return to the previous state by restoring that backup rather than attempting an ad hoc repair. Record which check failed, such as missing users, broken provider configuration or sign-in errors, and decide whether to fix the restore or roll back. Your quote should state who performs the rollback, how long your team needs to approve it, and whether the work includes a second attempt. Test this path on staging before production.
Does the upgrade require a commercial authentik license?
No. The PostgreSQL major upgrade itself does not depend on an authentik edition. authentik's repository places most code under the MIT license, while code in its enterprise directory uses a separate license, and the pricing page lists an Open Source edition alongside Enterprise and Enterprise Plus. Check whether any feature you rely on, such as Google Workspace or Entra ID integrations, is enterprise-only, since those features must still work after the database move. Confirm your edition and license terms with authentik before the change, not after.
How DeployOpen scopes and delivers the PostgreSQL upgrade
DeployOpen treats the PostgreSQL major upgrade under authentik as a planned change to the database that holds all of authentik's configuration and data. We agree the target version, the method and the verification steps in writing before any work starts, then run the change in your environment with a tested restore path.
How we scope
- Confirm your current authentik release and PostgreSQL version, and the target major version you need to reach.
- Record whether authentik runs on Docker Compose or Kubernetes, and whether PostgreSQL is bundled or separately managed.
- Agree in writing the backup, restore and verification checks, the maintenance window owner, and the rollback point.
How we build
- Rehearse the logical dump, stack stop, data directory backup and restore on a copy of your environment first.
- Check the restored database against authentik's running version before the stack is started against it.
- Review connection limits and PostgreSQL client settings so the upgraded database matches your authentik release.
How we hand over
- Deliver a runbook with the exact steps, commands and configuration changes used for your Compose or Kubernetes setup.
- Document the backup artifacts, their locations, retention and the restore procedure your team can repeat.
- Walk your platform and database owners through the verification results and the open items they must confirm.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer if your team wants help with later changes.
- Plan the next authentik and PostgreSQL support windows so the upgrade does not fall behind supported versions.
- Confirm support terms, response expectations and included work with the written scope before the engagement begins.
