Database Migrations | Supabase 简体中文

Database migrations are SQL statements that create, update, or delete your existing database schemas. They are a common way of tracking changes to your database over time.

Schema migrations

For this guide, we'll create a table called employees and see how we can make changes to it.

You will need to install the Supabase CLI and start the local development stack.

Note

If a lock timeout error occurs, in your migration file, consider increasing your lock_timeout setting.

Create your first migration file

To get started, generate a new migration to store the SQL needed to create our employees table.
```
supabase migration new create_employees_table
```

Add the SQL to your migration file

This creates a new migration file in supabase/migrations directory.

To that file, add the SQL to create this employees table.

create table if not exists employees (
  id bigint primary key generated always as identity,
  name text not null,
  email text,
  created_at timestamptz default now()
);

Apply your first migration

Run this migration to create the employees table.

Now you can visit your new employees table in the local Dashboard.
```
supabase migration up
```

Modify your employees table

Next, modify your employees table by adding a column for department.
```
supabase migration new add_department_column
```

Add a new column to your table

To that new migration file, add the SQL to create a new department column.
```
alter table if exists public.employees
add department text default 'Hooli';
```

Apply your second migration

Run this migration to update your existing employees table.
```
supabase migration up
```

Finally, you should see the department column added to your employees table in the local Dashboard.

Note

View the complete code for this example on GitHub.

Seeding data

Now that you are managing your database with migrations, it would be great have some seed data to use every time you reset the database.

Populate your table

Create a seed script in supabase/seed.sql.

To that file, add the SQL to insert data into your employees table.
```
insert into public.employees
  (name)
values
  ('Erlich Bachman'),
  ('Richard Hendricks'),
  ('Monica Hall');
```

Reset your database

Reset your database to reapply migrations and populate with seed data.
```
supabase db reset
```

You should now see the employees table, along with your seed data in the Dashboard! All of your database changes are captured in code, and you can reset to a known state at any time, complete with seed data.

Diffing changes

This workflow is great if you know SQL and are comfortable creating tables and columns. If not, you can still use the Dashboard to create tables and columns, and then use the CLI to diff your changes and create migrations.

The SQL that db diff generates depends on your project's diff engine.

Which diff engine your project uses depends on config.toml. If it contains an [experimental.pgdelta] section with enabled = true, your project uses pg-delta. If the section is missing or enabled is false, your project uses the legacy migra engine. See Diff engines for how the two differ and how to switch.

Note

If you'd rather declare the state you want your database to be in and have migrations generated for you, manage your schema declaratively instead. On pg-delta, edit files in supabase/schemas/ and generate migrations with supabase db schema declarative sync. Don't use db diff to generate migrations from declarative files on that engine, because it never uses supabase/schemas/ as its baseline. On the legacy migra engine, db schema declarative sync won't run and db diff does read supabase/schemas/, so follow Declarative schemas on the legacy migra engine instead. See Declarative database schemas.

Caution

Only use the Dashboard to make schema changes on your local database, then capture them with supabase db diff. Making schema changes directly on your remote database (via the SQL editor or Table Editor) bypasses the migration history and will cause db push to fail with sync errors. Once you're using migrations, all schema changes to your remote database should go through migration files only.

Create your table from the Dashboard

Create a new table called cities, with columns id, name and population.

Then generate a schema diff.
```
supabase db diff -f create_cities_table
```

Add schema diff as a migration

A new migration file is created for you.

Alternately, you can copy the table definitions directly from the Table Editor.

create table "public"."cities" (
  "id" bigint primary key generated always as identity,
  "name" text,
  "population" bigint
);

Test your migration

Test your new migration file by resetting your local database.
```
supabase db reset
```

The last step is deploying these changes to a live Supabase project.

Deploy your project

You've been developing your project locally, making changes to your tables via migrations. It's time to deploy your project to the Supabase Platform and start scaling up to millions of users!

Head over to Supabase and create a new project to deploy to.

Sign in to the Supabase CLI

Sign in to the Supabase CLI using an auto-generated Personal Access Token.
```
supabase login
```

Link your project

Link to your remote project by selecting from the on-screen prompt.
```
supabase link
```

Deploy database migrations

Push your migrations to the remote database.
```
supabase db push
```

Deploy database seed data (optional)

Push your migrations and seed the remote database.
```
supabase db push --include-seed
```

Visiting your live project on Supabase, you'll see a new employees table, complete with the department column you added in the second migration above.

Working with a team

When multiple developers share a Supabase project, a few rules keep migrations from getting out of sync.

The golden rule: never change the remote database directly. Once you're using migrations, all schema changes — even small ones — should go through migration files. Using the Dashboard's SQL editor or Table Editor on your remote database bypasses the migration history, and db push will start failing with sync errors.

The team workflow:

Create a migration locally

Each developer creates migration files on their own branch, never touching the remote database directly.
```
supabase migration new your_change_description
```

Test and commit

Reset your local database to apply the migration, then commit the migration file to git.

supabase db reset
git add supabase/migrations
git commit -m "add migration: your_change_description"

Pull and reset when a teammate merges a migration

After pulling new migration files from git, reset your local database to apply them.
```
git pull
supabase db reset
```

One person deploys to remote

Coordinate so only one person runs db push at a time. Migration files are applied in timestamp order, so concurrent pushes from different machines can cause conflicts.
```
supabase db push
```

Note

For a more automated deployment approach, consider using Supabase Branching or a CI/CD pipeline that runs supabase db push on merge to your main branch.

Diagnosing and fixing sync errors

If db push fails with errors suggesting you run supabase migration repair, your local migration files and the remote database's migration history are out of sync. Here's how to diagnose and fix it.

How migration tracking works

Supabase tracks which migrations have been applied on each database in a table called supabase_migrations.schema_migrations. When you run supabase db push, it compares your local supabase/migrations folder against that table and runs only the ones not yet applied, in order.

Git tracks your migration files. Supabase tracks what's been applied to each database. These are two separate systems that need to stay in sync.

Step 1: Check what's out of sync

Start by listing the migration status across local and remote:

supabase migration list

This shows which migrations are applied locally, which are applied on the remote, and where they diverge.

Step 2: If you made changes on the remote database directly

Pull the current remote state into a migration file to get back in sync:

supabase db pull

This creates a new migration file capturing the current remote schema. Commit it to git, then follow the standard workflow going forward.

What db pull captures in managed schemas depends on your project's diff engine.

On pg-delta, a plain supabase db pull captures your customizations automatically, such as a trigger on auth.users that calls a function in public, or RLS policies on storage.objects. A trigger whose function lives inside auth or storage is excluded even if you created it, so deliver it through a versioned migration. On the legacy migra engine, the initial pull's pg_dump skips those schemas, but the diff pass that follows appends your triggers and RLS policies there to the same migration, and later pulls diff them too. Older CLI versions excluded auth and storage entirely and printed a message saying so. If you see that message, capture existing customizations once with explicit pulls:

supabase db pull --schema auth
supabase db pull --schema storage

See Diff engines for what each engine captures in managed schemas.

Step 3: If the migration history table is wrong

If a migration shows as missing in the remote history table but the schema change is already there (for example, it was applied manually), you can mark it as applied without re-running it:

supabase migration repair --status applied <migration-timestamp>

Or if a migration is recorded as applied but was never run:

supabase migration repair --status reverted <migration-timestamp>

Caution

migration repair updates the tracking table only — it does not apply or revert any SQL. Use it to correct the history record when you know the actual database state is correct.