Skip to content

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

add restore from platform to self-hosted how-to

Andrey A.0312cc56cef5
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index a57f010ade7..dc336db3fb8 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -2827,6 +2827,7 @@ export const self_hosting: NavMenuConstant = {
items: [
{ name: 'Overview', url: '/guides/self-hosting' },
{ name: 'Self-Hosting with Docker', url: '/guides/self-hosting/docker' },
+ { name: 'Restore from Platform', url: '/guides/self-hosting/restore-from-platform' },
{
name: 'Configuration',
items: [{ name: 'Enabling MCP server', url: '/guides/self-hosting/enable-mcp' }],
diff --git a/apps/docs/content/guides/self-hosting.mdx b/apps/docs/content/guides/self-hosting.mdx
index 37ac3e9b571..6802d6b3dfe 100644
--- a/apps/docs/content/guides/self-hosting.mdx
+++ b/apps/docs/content/guides/self-hosting.mdx
@@ -28,10 +28,10 @@ The fastest and recommended way to self-host Supabase is using Docker.
</div>
</div>
-## Other deployment options
+## Community-driven projects
{/* supa-mdx-lint-disable-next-line Rule004ExcludeWords */}
-There are several other ways to deploy Supabase with the help of community-driven projects. These projects may be outdated and are seeking active maintainers. If you're interested in maintaining one of these projects, [contact the Community team](/open-source/contributing/supasquad).
+There are several other options to deploy Supabase. If you're interested in helping these projects, visit our [Community](/contribute) page.
<div className="grid md:grid-cols-12 gap-4 not-prose">
{selfHostingCommunity.map((x) => (
@@ -41,7 +41,6 @@ There are several other ways to deploy Supabase with the help of community-drive
title={
<span className="flex items-center gap-2">
{x.name}
- <Badge>Maintainer needed</Badge>
</span>
}
>
diff --git a/apps/docs/content/guides/self-hosting/docker.mdx b/apps/docs/content/guides/self-hosting/docker.mdx
index 365055a18b6..d1f39a54d5c 100644
--- a/apps/docs/content/guides/self-hosting/docker.mdx
+++ b/apps/docs/content/guides/self-hosting/docker.mdx
@@ -27,7 +27,7 @@ This guide assumes you're comfortable with:
- Docker and Docker Compose
- Networking fundamentals (ports, DNS, firewalls)
-If you're new to these topics, consider starting with [managed Supabase](/dashboard) for free, or try [local development with the CLI](/docs/guides/local-development).
+If you're new to these topics, consider starting with managed [Supabase platform](/dashboard) for free.
You need the following installed on your system:
@@ -147,7 +147,7 @@ sh ./utils/generate-keys.sh
The script is experimental, so review the output before proceeding and also check `.env` after it's updated by the script.
-Alternatively, configure all secrets manually as follows.
+**Alternatively, configure all secrets manually as follows.**
### Configure database password
diff --git a/apps/docs/content/guides/self-hosting/restore-from-platform.mdx b/apps/docs/content/guides/self-hosting/restore-from-platform.mdx
new file mode 100644
index 00000000000..05ae9cbc32b
--- /dev/null
+++ b/apps/docs/content/guides/self-hosting/restore-from-platform.mdx
@@ -0,0 +1,180 @@
+---
+title: 'Restore a Platform Project to Self-Hosted'
+description: 'Restore your database from the Supabase platform to a self-hosted instance.'
+subtitle: 'Restore your database from the Supabase platform to a self-hosted instance.'
+---
+
+This guide walks you through restoring your database from a Supabase platform project to a [self-hosted Docker instance](/docs/guides/self-hosting/docker). Storage objects transfer or redeploying edge functions is not covered here.
+
+## Before you begin
+
+You need:
+
+- A new self-hosted Supabase instance ([Docker setup guide](/docs/guides/self-hosting/docker))
+- [Supabase CLI](/docs/guides/local-development/cli/getting-started) installed (or use `npx supabase`)
+- [Docker Desktop](https://docs.docker.com/get-started/get-docker/) installed (required by the CLI)
+- `psql` installed ([official installation guide](https://www.postgresql.org/download/))
+- Your Supabase database passwords (for platform and self-hosted)
+
+## Step 1: Get your platform connection string
+
+On your managed Supabase project dashboard, click [**Connect**](/dashboard/project/_?showConnect=true) and copy the connection string (use the session pooler or direct connection).
+
+## Step 2: Back up your platform database
+
+Export roles, schema, and data as three separate SQL files:
+
+```bash
+supabase db dump --db-url "[CONNECTION_STRING]" -f roles.sql --role-only
+```
+
+```bash
+supabase db dump --db-url "[CONNECTION_STRING]" -f schema.sql
+```
+
+```bash
+supabase db dump --db-url "[CONNECTION_STRING]" -f data.sql --use-copy --data-only
+```
+
+This produces SQL files that are compatible across Postgres versions.
+
+<Admonition type="note">
+
+Using `supabase db dump` executes `pg_dump` under the hood but applies Supabase-specific filtering - it excludes internal schemas, strips reserved roles, and adds idempotent `IF NOT EXISTS` clauses. Using raw `pg_dump` directly will include Supabase internals and cause permission errors during restore. CLI requires Docker because it runs `pg_dump` inside a container from the Supabase Postgres image rather than requiring a local Postgres installation.
+
+</Admonition>
+
+## Step 3: Prepare your self-hosted instance
+
+Before restoring, check the following on your self-hosted instance:
+
+- **Extensions**: Enable any non-default extensions your Supabase project uses. You can check which extensions are active by querying `select * from pg_extension;` on your managed database (or check Database Extensions in Dashboard).
+
+## Step 4: Restore to your self-hosted database
+
+Connect to your self-hosted Postgres and restore the dump files. The [default](/docs/guides/self-hosting/docker#accessing-postgres) connection string for self-hosted Supabase is:
+
+```
+postgres://postgres.your-tenant-id:[POSTGRES_PASSWORD]@[your-domain]:5432/postgres
+```
+
+Where `[POSTGRES_PASSWORD]` is the value of `POSTGRES_PASSWORD` in your self-hosted `.env` file.
+
+Use your domain name, your server IP, or localhost for `[your-domain]` depending on whether you are running self-hosted Supabase on a VPS, or locally.
+
+Run `psql` to restore:
+
+```bash
+psql \
+ --single-transaction \
+ --variable ON_ERROR_STOP=1 \
+ --file roles.sql \
+ --file schema.sql \
+ --command 'SET session_replication_role = replica' \
+ --file data.sql \
+ --dbname "postgres://postgres.your-tenant-id:[POSTGRES_PASSWORD]@[your-domain]:5432/postgres"
+```
+
+Setting `session_replication_role` to `replica` disables triggers during the data import, preventing issues like double-encryption of columns.
+
+## Step 5: Verify the restore
+
+Connect to your self-hosted database and run a few checks:
+
+```bash
+psql "postgres://postgres.your-tenant-id:[POSTGRES_PASSWORD]@[your-domain]:5432/postgres"
+```
+
+```sql
+-- Check your tables are present
+\dt public.*
+
+-- Verify row counts on key tables
+SELECT count(*) FROM auth.users;
+
+-- Check extensions
+SELECT * FROM pg_extension;
+```
+
+## What's included and what's not
+
+The database dump includes your schema, data, roles, RLS policies, database functions, triggers, and `auth.users`. However, several things require separate configuration on your self-hosted instance:
+
+| Requires manual setup | How to configure |
+| --- | --- |
+| JWT secrets and API keys | Generate new ones and update `.env` |
+| Auth provider settings (OAuth, Apple, etc.) | Configure `GOTRUE_EXTERNAL_*` variables in `.env` |
+| Edge functions | Manually copy to your self-hosted instance |
+| Storage objects | Transfer separately (not covered in this guide) |
+| SMTP / email settings | Configure `SMTP_*` variables in `.env` |
+| Custom domains and DNS | Point your DNS to the self-hosted server |
+
+## Auth considerations
+
+Your `auth.users` table and related data are included in the database dump, so user accounts are preserved. However:
+
+- **JWT secrets differ** between your platform and self-hosted instances. Existing tokens issued by the platform project will not be valid. Users will need to re-authenticate.
+- **Social auth providers** (Apple, Google, GitHub, etc.) need to be configured in your self-hosted `.env` file. Set the relevant `GOTRUE_EXTERNAL_*` variables. See the Auth repository [README](https://github.com/supabase/auth) for all available options.
+- **Redirect URLs** in your OAuth provider consoles (Apple Developer, Google Cloud Console, etc.) must be updated to point to your self-hosted hostname instead of `*.supabase.co`.
+
+## Postgres version compatibility
+
+Managed Supabase may run a newer Postgres version (Postgres 17) than the self-hosted Docker image (currently Postgres 15). The `supabase db dump` command produces plain SQL files that work across major Postgres versions.
+
+Keep in mind:
+
+- The data dump may include Postgres 17-only settings or reference tables/columns from newer Auth and Storage versions that don't exist on self-hosted yet. See [Version mismatches](#version-mismatches-between-platform-and-self-hosted) in the troubleshooting section.
+- Run the restore on a test self-hosted instance first to identify any incompatibilities.
+- Check that all extensions you use are available on the self-hosted Postgres version.
+
+## Troubleshooting
+
+### Version mismatches between platform and self-hosted
+
+The platform may run a newer Postgres version (17 vs 15) and newer Auth service versions than self-hosted. The data dump can contain settings, tables, or columns that don't exist on your new self-hosted instance.
+
+**Common issues in `data.sql`:**
+
+- `SET transaction_timeout = 0` - a Postgres 17-only setting that fails on Postgres 15
+- `COPY` statements for tables that don't exist on self-hosted (e.g., `auth.oauth_clients`, `storage.buckets_vectors`, `storage.vector_indexes`)
+- `COPY` statements with columns added in newer Auth versions (e.g., `auth.flow_state` with `oauth_client_state_id`, `linking_target_id`)
+
+**Workaround:** Edit `data.sql` before restoring:
+
+```bash
+# Comment out PG17-only transaction_timeout
+sed -i 's/^SET transaction_timeout/-- &/' data.sql
+```
+
+For missing tables or column mismatches, comment out the relevant `COPY ... FROM stdin;` line and its corresponding `\.` terminator. Run the restore without `--single-transaction` first to identify all failures, then fix them and run the final restore with `--single-transaction`.
+
+Keeping your self-hosted configuration [up to date](https://github.com/supabase/supabase/blob/master/docker/CHANGELOG.md) will minimize these gaps.
+
+### Extension not available
+
+If the restore fails because an extension isn't available, check whether it's supported on your self-hosted Postgres version. You can list available extensions with:
+
+```sql
+SELECT * FROM pg_available_extensions;
+```
+
+### Connection refused
+
+Make sure your self-hosted Postgres port is accessible. In the default [self-hosted Supabase](/docs/guides/self-hosting/docker#accessing-postgres) setup, the user is `postgres.your-tenant-id` with Supavisor on port `5432`.
+
+### Legacy Studio configuration
+
+Studio in self-hosted Supabase historically used `supabase_admin` role (superuser) instead of `postgres`. Objects created via Studio UI were owned by `supabase_admin`. Check your `docker-compose.yml` [configuration](https://github.com/supabase/supabase/blob/2cb5befaa377a42b6d6ca152b98105b59054f2f4/docker/docker-compose.yml#L30) to see if `POSTGRES_USER_READ_WRITE` is set to `postgres`.
+
+### Custom roles missing passwords
+
+If you created custom database roles with the `LOGIN` attribute on your platform project, their passwords are not included in the dump. Set them manually after restore:
+
+```sql
+ALTER ROLE your_custom_role WITH PASSWORD 'new-password';
+```
+
+### Additional resources
+
+- [Backup and Restore using the CLI](/docs/guides/platform/migrating-within-supabase/backup-restore)
+- [Restore Dashboard backup](/docs/guides/platform/migrating-within-supabase/dashboard-restore)
diff --git a/apps/docs/content/troubleshooting/transferring-from-cloud-to-self-host-in-supabase-2oWNvW.mdx b/apps/docs/content/troubleshooting/transferring-from-cloud-to-self-host-in-supabase-2oWNvW.mdx
index 0d682cc00bf..3ee20895f7f 100644
--- a/apps/docs/content/troubleshooting/transferring-from-cloud-to-self-host-in-supabase-2oWNvW.mdx
+++ b/apps/docs/content/troubleshooting/transferring-from-cloud-to-self-host-in-supabase-2oWNvW.mdx
@@ -1,5 +1,5 @@
---
-title = "Transferring from cloud to self-host in Supabase"
+title = "Transferring from platform to self-hosted Supabase"
github_url = "https://github.com/orgs/supabase/discussions/22712"
date_created = "2024-04-14T15:19:10+00:00"
topics = [ "database", "self-hosting" ]
@@ -7,10 +7,33 @@ keywords = [ "migrate", "pg_dump", "psql", "self-host" ]
database_id = "c6b6ae3c-1b5b-4ba8-a40f-5f2ca1f007e2"
---
-To migrate from cloud to self-hosting, you can use the [pg_dump](https://www.postgresql.org/docs/9.6/app-pgdump.html) command to export your database to an SQL file, which then you can run on any database to load the same data in.
+For a detailed, step-by-step guide on restoring your database from the Supabase platform to a [self-hosted Supabase](/docs/guides/self-hosting) instance, see [Restore a Platform Project to Self-Hosted](/docs/guides/self-hosting/restore-from-platform).
-You can then try to import your SQL files using psql from the terminal:
+### Quick reference
-`psql -h 127.0.0.1 -p 5432 -d postgres -U postgres -f <dump-file-name>.sql`
+Back up your cloud database:
-You can also find some useful information about self-hosting here: https://supabase.com/docs/guides/self-hosting.
+```bash
+supabase db dump --db-url "[CONNECTION_STRING]" -f roles.sql --role-only
+```
+
+```bash
+supabase db dump --db-url "[CONNECTION_STRING]" -f schema.sql
+```
+
+```bash
+supabase db dump --db-url "[CONNECTION_STRING]" -f data.sql --use-copy --data-only
+```
+
+Restore to your self-hosted instance:
+
+```bash
+psql \
+ --single-transaction \
+ --variable ON_ERROR_STOP=1 \
+ --file roles.sql \
+ --file schema.sql \
+ --command 'SET session_replication_role = replica' \
+ --file data.sql \
+ --dbname "postgres://postgres.your-tenant-id:[POSTGRES_PASSWORD]@[your-domain]:5432/postgres"
+```