Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(self-hosted): update pg 17 upgrade how-to (#46989)

Andrey A.f6d0b9eda12a
diff --git a/apps/docs/content/guides/self-hosting/postgres-upgrade-17.mdx b/apps/docs/content/guides/self-hosting/postgres-upgrade-17.mdx
index ef94ac11a7a..fc107811f9a 100644
--- a/apps/docs/content/guides/self-hosting/postgres-upgrade-17.mdx
+++ b/apps/docs/content/guides/self-hosting/postgres-upgrade-17.mdx
@@ -4,40 +4,27 @@ description: 'Start a new self-hosted Supabase deployment with Postgres 17, or u
subtitle: 'Start a new self-hosted Supabase deployment with Postgres 17, or upgrade an existing Postgres 15 installation.'
---
-Self-hosted Supabase ships with Postgres 15 by default. This guide covers two scenarios:
+Self-hosted Supabase ships with Postgres 17 by default. This guide covers two scenarios:
- **New deployment** - start fresh with Postgres 17 (no existing data)
- **Upgrade existing deployment** - migrate from Postgres 15 to Postgres 17 using `pg_upgrade`
-## Before you begin
-
-- Complete the [Self-Hosting with Docker](/docs/guides/self-hosting/docker) setup
-- Your current database image should be `supabase/postgres:15.x`
-
## New deployment with Postgres 17
-If you are starting a new self-hosted Supabase instance with **no existing data**, use the Postgres 17 compose override:
+Postgres 17 is the default, so a new self-hosted instance with **no existing data** starts on Postgres 17 - no override needed:
```sh
-docker compose -f docker-compose.yml -f docker-compose.pg17.yml up -d
+docker compose up -d
```
-This uses the `docker-compose.pg17.yml` override file which swaps the database image:
+The rest of the setup is unchanged (see the Docker install [guide](/docs/guides/self-hosting/docker)).
-```yaml name=docker-compose.pg17.yml
-services:
- db:
- image: supabase/postgres:17.6.1.084
-```
-
-<Admonition type="tip">
+<Admonition type="note" title="GraphQL is off by default">
-If you use the override file, remember to include both compose files when running commands. Alternatively, you can update the image tag directly in `docker-compose.yml` instead of using an override.
+On a fresh Postgres 17 deployment, the `pg_graphql` extension is **disabled by default**. Enable it from Studio (**Database** > **Extensions**) or with `create extension pg_graphql;`. Databases that already use GraphQL keep it after an upgrade.
</Admonition>
-The rest of the setup is the same as for Postgres 15 (see the Docker install [guide](/docs/guides/self-hosting/docker)).
-
{/* supa-mdx-lint-disable-next-line Rule003Spelling */}
If the new Postgres 17 container fails to start, make sure to check for an old `db-config` Docker volume. See [Postgres 17 fails to start with a leftover db-config volume](#postgres-17-fails-to-start-with-a-leftover-db-config-volume) for details.
@@ -54,7 +41,7 @@ Upgrading an existing deployment uses `pg_upgrade` to migrate data in place. The
5. Runs additional tasks inside a temporary Postgres 17 container (re-enables extensions, applies patches, runs `VACUUM ANALYZE`)
6. Swaps data directories (the original is kept as a backup)
7. Starts self-hosted Supabase with Postgres 17
-8. Applies additional role migrations (new in Postgres 17)
+8. Applies post-upgrade migrations and reconciles extension versions to the target image
### Create a backup
@@ -121,12 +108,6 @@ The script might require your confirmation at some steps (e.g., while checking f
### After the upgrade
-After a successful upgrade, always use both compose files:
-
-```sh
-docker compose -f docker-compose.yml -f docker-compose.pg17.yml up -d
-```
-
To verify that Postgres 17 is running:
```sh
@@ -152,14 +133,14 @@ Do not delete `data.bak.pg15` until you have verified the upgrade. Rollback is o
If you need to revert to Postgres 15 (run the following commands as root):
```sh
-docker compose -f docker-compose.yml -f docker-compose.pg17.yml down && \
+docker compose down && \
rm -rf ./volumes/db/data && \
mv ./volumes/db/data.bak.pg15 ./volumes/db/data && \
-docker compose run --rm db chown -R postgres:postgres /etc/postgresql-custom/ && \
-docker compose up -d
+docker compose -f docker-compose.yml -f docker-compose.pg15.yml run --rm db chown -R postgres:postgres /etc/postgresql-custom/ && \
+docker compose -f docker-compose.yml -f docker-compose.pg15.yml up -d
```
-This restores the original data directory, fixes file ownership on the `db-config` volume (Supabase's Postgres 15 and 17 images use different user IDs), and starts with the old Postgres 15 image.
+This restores the original data directory, fixes file ownership on the `db-config` volume, and starts with the old Postgres 15 image. The Postgres 15 override is required because Supabase's Postgres 15 and 17 images use different user IDs, so the `chown` and startup must run as Postgres 15.
### Custom Postgres configuration
@@ -197,7 +178,7 @@ The upgrade script delegates the core migration work to two scripts from the [su
**Phase 1 - Migrate data (Postgres 15 container):**
-1. Disables extensions that are incompatible with `pg_upgrade` (`pg_graphql`, `pg_stat_monitor`, `pg_backtrace`, `wrappers`, `pgrouting`) and generates SQL to re-enable them after the upgrade
+1. Disables extensions that are incompatible with `pg_upgrade` (`pg_graphql`, `pg_stat_monitor`, `pg_backtrace`) and generates SQL to re-enable them after the upgrade
2. Temporarily grants superuser to the `postgres` role (required by `pg_upgrade`)
3. Extracts the previously saved Postgres 17 binaries tarball and runs `initdb` to create a new empty database
4. Runs `pg_upgrade --check` to verify the upgrade can succeed before making changes
@@ -213,7 +194,7 @@ The upgrade script delegates the core migration work to two scripts from the [su
5. Grants predefined roles (`pg_monitor`, `pg_read_all_data`, `pg_signal_backend`, and on Postgres 16+ also `pg_create_subscription`) and revokes the temporary superuser grant
6. Restarts Postgres and runs `vacuumdb --all --analyze-in-stages` to rebuild optimizer statistics
-After both phases complete, the upgrade script preserves the original Postgres 15 data directory as a backup and starts the full Supabase stack with Postgres 17.
+After both phases, the upgrade script applies migrations that normally run only on a fresh install, and reconciles installed extensions to the target image's versions. It then preserves the original Postgres 15 data directory as a backup and starts the full Supabase stack with Postgres 17.
## Troubleshooting
@@ -318,5 +299,5 @@ docker compose run --rm db \
Start Postgres 15:
```sh
-docker compose up -d
+docker compose -f docker-compose.yml -f docker-compose.pg15.yml up -d
```