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#

There are a few methods available to upgrade your project.

pg_upgrade#

note

This upgrade method is currently in Beta, and is being slowly made available to projects.

pg_upgrade performs an in-place upgrade on your database. For projects larger than 1GB, pg_upgrade is generally faster than a pause+restore cycle, and the speed advantage grows with the size of the database.

Additionally, if a pg_upgrade upgrade should fail, your original DB would be brought back up online and be able to service requests.

As a rough rule of thumb, pg_upgrade operates at ~100mbps (when executing an upgrade on your data). Using the size of your database, you can use this metric to derive an approximate sense of the downtime window necessary for the upgrade. During this window, you should plan for your DB and associated services to be unavailable.

Pause + Restore#

note

This method is only available for projects on the Free plan. For projects on the Pro plan, please contact support for assistance with upgrading.

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.

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.
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.

Note that a pause + restore upgrade involves tearing down your project's resources before bringing them back up again. If the restore process should fail, manual intervention from Supabase support will be required to bring your project back online.

Caveats#

Regardless of the upgrade method, a few caveats apply:

Logical Replication

If you are using logical replication, the replication slots will not be preserved by the upgrade process. You will need to manually recreate them after the upgrade with the method pg_create_logical_replication_slot. Refer to the Postgres docs on Replication Management Functions for more details about the method.

Breaking changes

Newer versions of services can break functionality or change the performance characteristics you rely on. If your project is eligible for an upgrade, you will be able to find your current service versions from within the Supabase dashboard.

Breaking changes are generally only present in major version upgrades of Postgres and PostgREST. You can find their respective release notes at:

If you are upgrading from a significantly older version, you will need to consider the release notes for any intermediary releases as well.

Post-upgrade validation

Supabase performs extensive pre- and post-upgrade validations to ensure that the database has been correctly upgraded. However, you should plan for your own application-level validations, as there might be changes you might not have anticipated, and this should be budgeted for when planning your downtime window.

Migrate your project#

Migrating projects can be achieved using the Supabase CLI. 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.
Install Supabase CLI.
Create a new Supabase project.
Install Docker Desktop for your platform.
Set environment variables for the old project's database URL as $OLD_DB_URL and the new project's as $NEW_DB_URL. To find the database URL for a project, go to the project's dashboard page Project Settings/Database and look at Connection string / URI. For example, to set the $OLD_DB_URL you would run export OLD_DB_URL=postgresql://postgres:[YOUR-PASSWORD]@db.[YOUR-PROJECT-REF#].supabase.co:5432/postgres.

Backup your old database#

Run the following command from your terminal:

supabase db dump --db-url "$OLD_DB_URL" -f roles.sql --role-only
supabase db dump --db-url "$OLD_DB_URL" -f schema.sql
supabase db dump --db-url "$OLD_DB_URL" -f data.sql --use-copy --data-only

Restore to your new project#

In your new project:

Enable Database Webhooks if you enabled them in your old project.
Enable any extensions that were enabled in your old project.

Then run the following command from your terminal:

psql \
  --single-transaction \
  --variable ON_ERROR_STOP=1 \
  --file roles.sql \
  --file schema.sql \
  --file data.sql \
  --dbname "$NEW_DB_URL"

Notes:

If you have created any custom roles with login attribute, you have to manually set their passwords in the new project.
If you receive any permission errors when running supabase db dump --db-url "$OLD_DB_URL" -f schema.sql, you may need to edit the schema.sql file and change any lines saying OWNER TO "supabase_admin" to OWNER TO "postgres".

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.

// npm install @supabase/supabase-js@1
const { createClient } = require('@supabase/supabase-js')
const OLD_PROJECT_URL = 'https://xxx.supabase.co'
const OLD_PROJECT_SERVICE_KEY = 'old-project-service-key-xxx'
const NEW_PROJECT_URL = 'https://yyy.supabase.co'
const NEW_PROJECT_SERVICE_KEY = 'new-project-service-key-yyy'
;(async () => {
  const oldSupabaseRestClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY, {
    db: {
      schema: 'storage',
    },
  })
  const oldSupabaseClient = createClient(OLD_PROJECT_URL, OLD_PROJECT_SERVICE_KEY)
  const newSupabaseClient = createClient(NEW_PROJECT_URL, NEW_PROJECT_SERVICE_KEY)
  // make sure you update max_rows in postgrest settings if you have a lot of objects
  // or paginate here
  const { data: oldObjects, error } = await oldSupabaseRestClient.from('objects').select()
  if (error) {
    console.log('error getting objects from old bucket')
    throw error
  }
  for (const objectData of oldObjects) {
    console.log(`moving ${objectData.id}`)
    try {
      const { data, error: downloadObjectError } = await oldSupabaseClient.storage
        .from(objectData.bucket_id)
        .download(objectData.name)
      if (downloadObjectError) {
        throw downloadObjectError
      }
      const { _, error: uploadObjectError } = await newSupabaseClient.storage
        .from(objectData.bucket_id)
        .upload(objectData.name, data, {
          upsert: true,
          contentType: objectData.metadata.mimetype,
          cacheControl: objectData.metadata.cacheControl,
        })
      if (uploadObjectError) {
        throw uploadObjectError
      }
    } catch (err) {
      console.log('error moving ', objectData)
      console.log(err)
    }
  }
})()

Transfer to a different organization#

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 infrastrusture, see project transfers.

Edit this page on GitHub