Migrating and Upgrading Projects

Supabase ships fast and we endeavor to add all new features to existing projects wherever possible. In some cases, access to new features require upgrading or migrating your Supabase project.

Upgrade your project#

When you pause and restore a project, the restored database includes the latest features. This method does include downtime, so be aware that your project will be inaccessible for a short period of time.

  1. On the General Settings page in the Dashboard, click Pause project. You will be redirected to the home screen as your project is pausing. This process can take several minutes.
  2. After your project is paused, click Restore project. The restoration can take several minutes depending on how much data your database has. You will receive an email once the restoration is complete.

Migrate your project#

Migrating projects can be achieved using standard PostgreSQL tooling. This is particularly useful for older projects (e.g. to use a newer Postgres version).

Before you begin#

  • Install Postgres so you can run psql and pg_dump.
  • Create a new Supabase project.
  • Store the old project's database URL as $OLD_DB_URL and the new project's as $NEW_DB_URL.

Migrate the database#

  1. Enable Database Webhooks in your new project if you enabled them in your old project.
  2. In your new project, enable all extensions that were enabled in your old project.
  3. Run the following command from your terminal:
1set -euo pipefail
2
3pg_dump \
4  --clean \
5  --if-exists \
6  --quote-all-identifiers \
7  --exclude-table-data 'storage.objects' \
8  --exclude-schema 'extensions|graphql|graphql_public|net|pgbouncer|pgsodium|pgsodium_masks|realtime|supabase_functions|pg_toast|pg_catalog|information_schema' \
9  --schema '*' \
10  --dbname "$OLD_DB_URL" \
11| sed 's/^DROP SCHEMA IF EXISTS "auth";$/-- DROP SCHEMA IF EXISTS "auth";/' \
12| sed 's/^DROP SCHEMA IF EXISTS "storage";$/-- DROP SCHEMA IF EXISTS "storage";/' \
13| sed 's/^CREATE SCHEMA "auth";$/-- CREATE SCHEMA "auth";/' \
14| sed 's/^CREATE SCHEMA "storage";$/-- CREATE SCHEMA "storage";/' \
15| sed 's/^ALTER DEFAULT PRIVILEGES FOR ROLE "supabase_admin"/-- ALTER DEFAULT PRIVILEGES FOR ROLE "supabase_admin"/' \
16> dump.sql
17
18psql \
19  --single-transaction \
20  --variable ON_ERROR_STOP=1 \
21  --file dump.sql \
22  --dbname "$NEW_DB_URL"

Enable publication on tables#

Replication for Realtime is disabled for all tables in your new project. On the Replication page in the Dashboard, select your new project and enable replication for tables that were enabled in your old project.

Migrate Storage objects#

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. If you have more than 10k objects, we can move the objects for you. Just contact us at support@supabase.com.

1// npm install @supabase/supabase-js@1
2const { createClient } = require('@supabase/supabase-js')
3
4const OLD_PROJECT_URL = 'https://xxx.supabase.co'
5const OLD_PROJECT_SERVICE_KEY = 'old-project-service-key-xxx'
6
7const NEW_PROJECT_URL = 'https://yyy.supabase.co'
8const NEW_PROJECT_SERVICE_KEY = 'new-project-service-key-yyy'
9
10;(async () => {
11  const oldSupabaseRestClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY, {
12    schema: 'storage',
13  })
14  const oldSupabaseClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY)
15  const newSupabaseClient = createClient(NEW_PROJECT_URL, NEW_PROJECT_SERVICE_KEY)
16
17  // make sure you update max_rows in postgrest settings if you have a lot of objects
18  // or paginate here
19  const { data: oldObjects, error } = await oldSupabaseRestClient.from('objects').select()
20  if (error) {
21    console.log('error getting objects from old bucket')
22    throw error
23  }
24
25  for (const objectData of oldObjects) {
26    console.log(`moving ${objectData.id}`)
27    try {
28      const { data, error: downloadObjectError } = await oldSupabaseClient.storage
29        .from(objectData.bucket_id)
30        .download(objectData.name)
31      if (downloadObjectError) {
32        throw downloadObjectError
33      }
34
35      const { _, error: uploadObjectError } = await newSupabaseClient.storage
36        .from(objectData.bucket_id)
37        .upload(objectData.name, data, {
38          upsert: true,
39          contentType: objectData.metadata.mimetype,
40          cacheControl: objectData.metadata.cacheControl,
41        })
42      if (uploadObjectError) {
43        throw uploadObjectError
44      }
45    } catch (err) {
46      console.log('error moving ', objectData)
47      console.log(err)
48    }
49  }
50})()