|
1 | 1 | --- |
2 | 2 | title: Migrating within Supabase |
3 | | -subtitle: Migrate from one Supabase project to another |
| 3 | +subtitle: Learn how to migrate from one Supabase project to another |
4 | 4 | --- |
5 | 5 |
|
6 | | -Migrating projects can be achieved using the Supabase CLI. This is particularly useful for older projects (for example to use a newer Postgres version). |
| 6 | +If you are on a Paid Plan and have physical backups enabled, you should instead use the [Restore |
| 7 | +to another project feature](/docs/guides/platform/backups#restore-to-a-new-project) |
7 | 8 |
|
8 | | -### Before you begin |
| 9 | +## Database migration guides |
9 | 10 |
|
10 | | -- Install [Postgres](https://www.postgresql.org/download/) so you can run `psql` and `pg_dump`. |
11 | | -- Install the latest version of [Supabase CLI](/docs/guides/cli#installation). |
12 | | -- Create a new [Supabase project](https://supabase.com/dashboard). |
13 | | -- Install [Docker Desktop](https://www.docker.com) for your platform. |
14 | | -- Set environment variables for the old project's database URL as `$OLD_DB_URL` and the new project's as `$NEW_DB_URL`. |
15 | | - To find the database URL for a project, go to the project's dashboard page [Project Settings/Database](https://supabase.com/dashboard/project/_/settings/database) and look under `Connection string`. If your network provider supports IPv6, you can disable `Use connection pooling`. Otherwise, enable `Use connection pooling`. For the pooler mode, `Transaction` will work. |
| 11 | +If you need to migrate from one Supabase project to another, choose the appropriate guide below: |
16 | 12 |
|
17 | | -### Backup your old database |
| 13 | +### Backup file from the dashboard (\*.backup) |
18 | 14 |
|
19 | | -1. Run the following command from your terminal: |
| 15 | +Follow the [Restore dashboard backup guide](/docs/guides/platform/migrating-within-supabase/dashboard-restore) |
20 | 16 |
|
21 | | -```bash |
22 | | -supabase db dump --db-url "$OLD_DB_URL" -f roles.sql --role-only |
23 | | -supabase db dump --db-url "$OLD_DB_URL" -f schema.sql |
24 | | -supabase db dump --db-url "$OLD_DB_URL" -f data.sql --use-copy --data-only |
25 | | -``` |
| 17 | +### SQL backup files (\*.sql) |
26 | 18 |
|
27 | | -### Restore to your new project |
| 19 | +Follow the [Backup and Restore using the CLI guide](/docs/guides/platform/migrating-within-supabase/backup-restore) |
28 | 20 |
|
29 | | -In your new project: |
| 21 | +## Transfer my project to a different organization |
30 | 22 |
|
31 | | -1. Enable [Database Webhooks](https://supabase.com/dashboard/project/_/database/hooks) if you enabled them in your old project. |
32 | | -2. Enable any [extensions](https://supabase.com/dashboard/project/_/database/extensions) that were enabled in your old project. |
33 | | - |
34 | | -If you use [column encryption](/docs/guides/database/column-encryption), first copy the root encryption key to your new project using your [Personal Access Token](https://supabase.com/dashboard/account/tokens). |
35 | | - |
36 | | -```bash |
37 | | -export OLD_PROJECT_REF="<old_project_ref>" |
38 | | -export NEW_PROJECT_REF="<new_project_ref>" |
39 | | -export SUPABASE_ACCESS_TOKEN="<personal_access_token>" |
40 | | - |
41 | | -curl "https://api.supabase.com/v1/projects/$OLD_PROJECT_REF/pgsodium" \ |
42 | | - -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" | |
43 | | -curl "https://api.supabase.com/v1/projects/$NEW_PROJECT_REF/pgsodium" \ |
44 | | - -H "Authorization: Bearer $SUPABASE_ACCESS_TOKEN" \ |
45 | | - -X PUT --json @- |
46 | | -``` |
47 | | - |
48 | | -Then run the following command from your terminal: |
49 | | - |
50 | | -```bash |
51 | | -psql \ |
52 | | - --single-transaction \ |
53 | | - --variable ON_ERROR_STOP=1 \ |
54 | | - --file roles.sql \ |
55 | | - --file schema.sql \ |
56 | | - --command 'SET session_replication_role = replica' \ |
57 | | - --file data.sql \ |
58 | | - --dbname "$NEW_DB_URL" |
59 | | -``` |
60 | | - |
61 | | -Setting the `session_replication_role` to `replica` disables all triggers so that columns are not double encrypted. |
62 | | - |
63 | | -Troubleshooting notes: |
64 | | - |
65 | | -- If you have created any [custom roles](https://supabase.com/dashboard/project/_/database/roles) with `login` attribute, you have to manually set their passwords in the new project. |
66 | | -- If you run into any permission errors related to `supabase_admin` during restore, edit the `schema.sql` file and comment out any lines containing `ALTER ... OWNER TO "supabase_admin"`. |
67 | | - |
68 | | -### Preserving migration history |
69 | | - |
70 | | -If you were using Supabase CLI for managing migrations on your old database and would like to preserve the migration history in your newly restored project, you need to insert the migration records separately using the following commands. |
71 | | - |
72 | | -```bash |
73 | | -supabase db dump --db-url "$OLD_DB_URL" -f history_schema.sql --schema supabase_migrations |
74 | | -supabase db dump --db-url "$OLD_DB_URL" -f history_data.sql --use-copy --data-only --schema supabase_migrations |
75 | | -psql \ |
76 | | - --single-transaction \ |
77 | | - --variable ON_ERROR_STOP=1 \ |
78 | | - --file history_schema.sql \ |
79 | | - --file history_data.sql \ |
80 | | - --dbname "$NEW_DB_URL" |
81 | | -``` |
82 | | - |
83 | | -### Schema changes to `auth` and `storage` |
84 | | - |
85 | | -If you have modified the `auth` and `storage` schemas in your old project, such as adding triggers or RLS policies, you have to restore them separately. The Supabase CLI can help you diff the changes to these schemas using the following commands. |
86 | | - |
87 | | -```bash |
88 | | -supabase link --project-ref "$OLD_PROJECT_REF" |
89 | | -supabase db diff --linked --schema auth,storage > changes.sql |
90 | | -``` |
91 | | - |
92 | | -### Enable publication on tables |
93 | | - |
94 | | -Replication for Realtime is disabled for all tables in your new project. On the [Publications](https://supabase.com/dashboard/project/_/database/publications) page in the Dashboard, select your new project and enable replication for tables that were enabled in your old project. |
95 | | - |
96 | | -### Migrate storage objects |
97 | | - |
98 | | -The new project has the old project's Storage buckets, but the Storage objects need to be migrated manually. Use this script to move storage objects from one project to another. |
99 | | - |
100 | | -```js |
101 | | -// npm install @supabase/supabase-js@1 |
102 | | -const { createClient } = require('@supabase/supabase-js') |
103 | | - |
104 | | -const OLD_PROJECT_URL = 'https://xxx.supabase.co' |
105 | | -const OLD_PROJECT_SERVICE_KEY = 'old-project-service-key-xxx' |
106 | | - |
107 | | -const NEW_PROJECT_URL = 'https://yyy.supabase.co' |
108 | | -const NEW_PROJECT_SERVICE_KEY = 'new-project-service-key-yyy' |
109 | | - |
110 | | -;(async () => { |
111 | | - const oldSupabaseRestClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY, { |
112 | | - db: { |
113 | | - schema: 'storage', |
114 | | - }, |
115 | | - }) |
116 | | - const oldSupabaseClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY) |
117 | | - const newSupabaseClient = createClient(NEW_PROJECT_URL, NEW_PROJECT_SERVICE_KEY) |
118 | | - |
119 | | - // make sure you update max_rows in postgrest settings if you have a lot of objects |
120 | | - // or paginate here |
121 | | - const { data: oldObjects, error } = await oldSupabaseRestClient.from('objects').select() |
122 | | - if (error) { |
123 | | - console.log('error getting objects from old bucket') |
124 | | - throw error |
125 | | - } |
126 | | - |
127 | | - for (const objectData of oldObjects) { |
128 | | - console.log(`moving ${objectData.id}`) |
129 | | - try { |
130 | | - const { data, error: downloadObjectError } = await oldSupabaseClient.storage |
131 | | - .from(objectData.bucket_id) |
132 | | - .download(objectData.name) |
133 | | - if (downloadObjectError) { |
134 | | - throw downloadObjectError |
135 | | - } |
136 | | - |
137 | | - const { _, error: uploadObjectError } = await newSupabaseClient.storage |
138 | | - .from(objectData.bucket_id) |
139 | | - .upload(objectData.name, data, { |
140 | | - upsert: true, |
141 | | - contentType: objectData.metadata.mimetype, |
142 | | - cacheControl: objectData.metadata.cacheControl, |
143 | | - }) |
144 | | - if (uploadObjectError) { |
145 | | - throw uploadObjectError |
146 | | - } |
147 | | - } catch (err) { |
148 | | - console.log('error moving ', objectData) |
149 | | - console.log(err) |
150 | | - } |
151 | | - } |
152 | | -})() |
153 | | -``` |
154 | | - |
155 | | -### Transfer to a different organization |
156 | | - |
157 | | -Note that project migration is for transferring your projects to different regions. If you need to move your project to a different organization without touching the infrastructure, see [project transfers](/docs/guides/platform/project-transfer). |
| 23 | +Project migration is primarily for changing regions or upgrading to new major versions of the platform in some scenarios. If you need to move your project to a different organization without touching the infrastructure, see [project transfers](/docs/guides/platform/project-transfer). |
0 commit comments