The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.
TypeScript aialternativeauthdatabasedenoembeddingsexamplefirebasenextjsoauth2pgvectorpostgispostgrespostgresqlpostgrestrealtimesupabasevectorswebsockets
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.tsindex 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.mdxindex 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-drivetitle={<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.mdxindex 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.shThe 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 passworddiff --git a/apps/docs/content/guides/self-hosting/restore-from-platform.mdx b/apps/docs/content/guides/self-hosting/restore-from-platform.mdxnew file mode 100644index 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.mdxindex 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"+```