Production readiness
The AI keeps breaking the database: keeping Supabase migrations in Git with the CLI
When some database changes are made by your AI tool, some in the Supabase SQL Editor and some in the Table Editor, the migration files in your repository stop describing the real database. The AI then writes new changes against a database that no longer exists, and they break things. The fix is to capture what production really looks like with supabase db pull --remote, commit it, and from then on change the database only through migration files.
What you are seeing
The app worked yesterday. Today you asked your AI tool for a small change and something unrelated broke. Typical signs that the database and the code have drifted apart:
- A migration the AI wrote fails with errors like
relation "orders" already exists,column "status" does not existorpolicy ... already exists- it assumed a database that is not the one in production. - A column or policy you added by hand in the Table Editor or SQL Editor disappeared, or was silently overwritten, after the AI's next change.
- Your repository has a
supabase/migrationsfolder, but nobody can say whether it matches what runs in production. - The Database > Migrations page in the Supabase dashboard is empty or shows a different list than the files in your repository.
supabase db pushfails with sync errors, or refuses to run because the remote history does not match your local files.
Supabase's own guide names the cause directly: changing the remote database through the SQL Editor or Table Editor bypasses the migration history and causes db push sync errors (Deploy database migrations).
How to check it yourself
Run these on your own project only. Steps 1 to 3 only read information. Step 4 needs the Supabase CLI and only compares - it changes nothing.
1. See which migrations the database thinks it has
The Supabase CLI records every migration it applies in a table called supabase_migrations.schema_migrations (Deploy database migrations). The dashboard shows the same list under Database > Migrations. In the SQL Editor you can read it directly:
select version, name
from supabase_migrations.schema_migrations
order by version;version is the timestamp at the start of each migration file name, for example 20261121093000 for 20261121093000_add_orders.sql.- Error
relation "supabase_migrations.schema_migrations" does not exist: no migration was ever applied through the CLI. Every change in production was made some other way, so the files in your repository (if any) are not a record of it. Supabase notes this table is created by the CLI (knowledge base). - Rows are there: write down the last
version. You will compare it with your repository in step 2.
2. Compare with the files in your repository
Open your repository on GitHub and go to the supabase/migrations folder. Each file is named <timestamp>_<name>.sql. Compare the list with the result of step 1:
- The same timestamps in both places: the history matches. Drift can still exist if someone changed the database by hand afterwards - step 3 and 4 show that.
- Files in the repository that are missing from the database history: either they were never applied, or they were applied some other way (pasted into the SQL Editor, or run by an AI tool that does not record them).
- Versions in the database history with no file in the repository: someone applied a migration from another computer or branch and never committed it.
3. Take a snapshot of what production really looks like
These two queries list every column and every Row Level Security policy in the public schema. Save the results (the SQL Editor can export them as CSV) - they are your reference for what the app depends on today:
select table_name, column_name, data_type, is_nullable, column_default
from information_schema.columns
where table_schema = 'public'
order by table_name, ordinal_position;information_schema.columns is standard PostgreSQL (columns view).select tablename, policyname, cmd, roles, qual, with_check
from pg_policies
where schemaname = 'public'
order by tablename, policyname;pg_policies shows each policy's operation and its conditions (pg_policies).Look for tables, columns or policies you recognise from dashboard edits. If something in this list is not created anywhere in your migration files, production has drifted from the repository.
4. Let the CLI compare the two for you
If you have the Supabase CLI and a container runtime such as Docker Desktop or OrbStack (setup in step 1 of the fix), run this in the repository folder after supabase link. It builds a temporary database from your migration files and compares it with your linked project (db diff):
npx supabase migration list --remote
npx supabase db diff --remotemigration list shows local files and the remote history side by side, matched by timestamp (migration list). db diff prints the SQL that your migration files are missing to match production; it never asks for confirmation and only prints to the terminal unless you pass -f (which saves a new migration) or -o (which writes a review file).If db diff prints SQL statements, those are changes that exist in production but in no migration file. That is the drift.
Why it happens
A migration is a SQL file that describes one change to the database, such as "add a status column to orders". Played in order, the files in supabase/migrations should rebuild your database exactly. The CLI keeps track of which files a database has already received in supabase_migrations.schema_migrations, and db push applies only the ones that are missing, in timestamp order (Deploy database migrations).
That only works if every change goes through a file. In an AI-built app there are usually several ways to change the database at once:
- The AI tool. Lovable, for example, writes the SQL, asks for your approval in the chat, runs it on your Supabase project and saves the file under
supabase/migrations/(Lovable Supabase integration). Other tools may only print SQL for you to paste. - The Supabase Table Editor and SQL Editor, where a quick fix takes seconds and leaves no file behind.
- A second developer or a second AI session working from a different copy of the repository.
Each change made outside the files makes the repository a little more wrong. The AI tool reads the repository, not production, so its next migration is written for a database that no longer exists: it creates a table that is already there, alters a column that was renamed by hand, or recreates a policy you had tightened. Supabase's rule for teams is short: never change the remote database directly - all schema changes, even small ones, go through migration files (Deploy database migrations).
How to fix it
supabase db reset --remote on your production project to "start clean". With --remote that command drops all user-created objects in the remote database before replaying migrations (db reset) - your tables and their data included. db reset without --remote only touches the local copy and is safe.1. Install the CLI and connect it to your project
You need the repository on your computer (clone it from GitHub), Node.js 20 or newer, and a container runtime: Supabase points to Docker Desktop on Windows and Linux and recommends OrbStack on macOS (CLI getting started). In the repository folder:
# Install the CLI into this project
npm install supabase --save-dev
# Only if there is no supabase/config.toml in the repository yet
npx supabase init
# Sign in and connect this folder to your Supabase project
npx supabase login
npx supabase link --project-ref YOUR_PROJECT_REF/project/. link asks for the database password set when the project was created; it can be reset in the project's database settings.--remote flag of the current CLI. As of 2026-11-21 the CLI reference says --linked, --project-ref, --db-url and --local still work but are deprecated and will be removed in v4 (db push). If your installed version rejects --remote, run npx supabase --version and npx supabase db push --help and use the flag that version lists.2. Save a copy of the current schema
Before touching anything, dump the structure of production to a file. By default db dump contains only the schema - no data and no custom roles (db dump). It is a reference, not a backup of your data:
npx supabase db dump --remote -f schema-before-cleanup.sqlsupabase/migrations, so the CLI never treats it as a migration.3. Line up the migration history
Run npx supabase migration list --remote and look at each row where the local and remote columns differ:
- A file exists locally, the remote column is empty, but the change is already in production (you can see the table or column in the snapshot from check 3): it was applied by hand. Mark it as applied so
db pushdoes not run it a second time:npx supabase migration repair --status applied 20261121093000 --remote. - A file exists locally, the remote column is empty, and the change is not in production: leave it.
db pushwill apply it later - after you have read it. - A version exists remotely with no local file: someone applied a migration that was never committed.
npx supabase migration fetch --remotewrites migration files from the history table (migration fetch); check what it created before committing.
migration repair only edits the history table - it does not run or undo any SQL (Deploy database migrations). Use it only to record what has really happened.
4. Capture the drift in a new migration
Now turn everything that was changed by hand into a migration file. db pull --remote compares production with your migration files and writes the difference into a new file in supabase/migrations, then records it in the history table so it is not applied again (db pull). On a project that has never used migrations it writes the whole schema as the first file:
npx supabase db pull --remoteOpen the new file and read it. Supabase advises reviewing generated migrations because they can include GRANT and REVOKE statements (Managing environments) - those decide who can read your tables. If something in the file is a mistake you do not want to keep (a test table, a policy that is too open), do not edit production by hand again: write a new migration that removes it (step 6).
5. Check that files and production now match, then commit
npx supabase migration list --remote # every row should have both columns filled
npx supabase db diff --remote # should print no schema changes
git add supabase/migrations supabase/config.toml package.json package-lock.json
git commit -m "Capture production schema in migrations"
git pushsupabase/migrations folder is the record of your database. If you use Lovable, push to the branch it syncs with, so the AI tool sees the same files.6. Make every future change through a file
For changes you make yourself, create a migration, try it on the local database, then push it (Deploy database migrations):
npx supabase migration new add_order_status
# write the SQL into the new file in supabase/migrations, then:
npx supabase start # local database (first run downloads images)
npx supabase db reset # rebuilds the LOCAL database from all migrations
npx supabase db push --remote --dry-run # shows what would be applied
npx supabase db push --remote # applies it to production after a confirmationA migration file is plain SQL. For example, adding a column with a default and a check:
alter table public.orders
add column if not exists status text not null default 'new';
alter table public.orders
add constraint orders_status_check
check (status in ('new', 'paid', 'shipped', 'cancelled'));orders and the values to match your app. Existing rows get the default 'new', so the check passes for them. If the column already existed with other values, if not exists skips the first statement and the check can fail - look at the values first with select distinct status from public.orders;.If your AI tool applies migrations itself (as Lovable does), let it - but stop making schema changes in the Table Editor and SQL Editor. After each AI change, run npx supabase migration list --remote once: if the tool's new file shows up locally but not remotely although the change is live, record it with migration repair --status applied as in step 3. Add a standing instruction to the tool, for example:
Every change to the Supabase database schema (tables, columns, indexes,
policies, grants, functions, triggers) must be a new SQL file in
supabase/migrations. Never edit an existing migration file. Before writing a
migration, read the existing files in supabase/migrations so the new one
matches the current schema. Use "if not exists" / "if exists" where Postgres
supports it.Once this works, the next step is to stop testing on production. Supabase's GitHub integration can run the migrations of each pull request on a separate branch database and apply new migrations to production on merge (GitHub integration), and Supabase's Managing environments guide shows a staging and production setup with GitHub Actions. Check your plan's pricing before turning branching on.
When to get help
A project with a handful of tables and a few hand edits is an afternoon of careful work with the steps above. Get a second pair of eyes when:
db pullproduced a file with hundreds of lines and you cannot tell which parts are intentional, which are leftovers and which open your data (grant,create policy ... using (true)).- The history table and the repository disagree on many versions and you are not sure which changes really reached production.
- A broken AI migration already ran on production and some data looks wrong, not only the structure.
- The app has paying users and you want a staging setup so that the next AI change is tested before it reaches them.
Sources
Primary documentation this guide was checked against. Platforms change - if something here no longer matches, the source wins.
- Deploy database migrationsSupabase docs
- Managing environmentsSupabase docs
- Getting started with the Supabase CLISupabase docs
- supabase db pullSupabase CLI reference
- supabase db pushSupabase CLI reference
- supabase db diffSupabase CLI reference
- supabase db dumpSupabase CLI reference
- supabase db resetSupabase CLI reference
- supabase migration list and repairSupabase CLI reference
- supabase migration fetchSupabase CLI reference
- Error: relation supabase_migrations.schema_migrations does not existSupabase knowledge base
- GitHub integration (branching)Supabase docs
- Supabase integrationLovable docs
- The columns viewPostgreSQL docs
- pg_policiesPostgreSQL docs
Frequently asked questions
- What is a database migration, in plain words?
- A SQL file that describes one change to your database, such as adding a table or a column. The files are kept in
supabase/migrationsin your repository and applied in order, so the same set of files can rebuild the same database anywhere - on your computer, on a staging project or in production. - Can I still use the Supabase Table Editor?
- For looking at data and editing rows, yes. For changing the structure - tables, columns, policies - on production, Supabase's guidance is no: those edits bypass the migration history and cause
db pushsync errors. If you like the visual editor, use it on the local database started withsupabase startand turn the result into a file withsupabase db diff -f name. - Does `supabase db pull` change my production database?
- It does not change your tables. It writes a new migration file on your computer and inserts one row into the migration history table in the target database, so that file is not applied again. It asks for confirmation before doing so on a hosted project.
- Do I need Docker?
- For
db pull,db diffand the local database, yes - the CLI runs Postgres in a container. Supabase's getting-started guide names Docker Desktop on Windows and Linux and OrbStack (or Rancher Desktop, Podman, colima) on macOS. - My Lovable project already has a supabase/migrations folder. Is it in sync?
- Not necessarily. Lovable saves the migrations it runs there, but any change made in the Supabase dashboard is not in those files. Run the checks on this page - the history query,
migration list --remoteanddb diff --remote- to see whether the folder and production agree. - Is it safe to delete old migration files to clean up?
- Not on its own. The history table still lists them, and
migration listwill show the mismatch. The CLI hassupabase migration squashto combine local migrations into one file, but a remote squash resets the remote history table. Do it only after the setup on this page is stable, and ideally with help.
Related guides
Fixed-price audit
Want someone to check the whole app, not just this?
A review of data security, production readiness and App Store readiness for apps built with AI tools. 900 USD, a ranked list of fixes within 5 business days.