Preview a migration
Run a migration on a fresh copy of your database and see what it would do to production before you run it.
A migration that's instant on your laptop can lock a busy production table for minutes. Preview a migration runs it on a fresh copy of your database, on its own server, and shows you the locks, rewrites, rows and time first. Production is never touched.
It works for PostgreSQL, MySQL, MariaDB, MongoDB, ClickHouse and SQLite (not yet Redis and Valkey). What it can tell differs a little per engine: see Other engines.
What you get
- A verdict: Safe, Careful, Dangerous, or Fails (the migration errors on production's data).
- What to change, in plain words: use
CREATE INDEX CONCURRENTLY, add a constraintNOT VALIDthenVALIDATEit, add a column instead of changing its type, setlock_timeout, batch a largeUPDATE. - Each statement: time, rows changed, locks and what they block, tables rewritten, indexes built, tables dropped.
- Row-level security (PostgreSQL, below): a new table your API can reach without it, row-level security turned off, a policy dropped, a policy that lets every row through.
Row-level security
If your app talks to PostgreSQL through an API such as Supabase or PostgREST, AI-written migrations often create a table without row-level security, or turn it off to get past a permission error. The preview compares the copy's row-level security before and after the migration, and flags:
| Finding | Verdict |
|---|---|
A new table your API's roles (anon, authenticated, ...) can use without row-level security, in a database that already uses it | Careful |
DISABLE ROW LEVEL SECURITY on a table | Careful; Dangerous when anon can read it (anyone with your public key reads every row) |
| A policy dropped (not recreated under the same name) | Careful |
A policy whose rule is always true (USING (true)) for your API's roles | Careful |
Each comes with what to do, such as "Turn on row-level security and add a policy" in the same migration. Rowsafe reads only the catalog: table and policy names and flags, never rows or a policy's rule. These are the same rules as Pulse's row-level security check. When the migration can't run (it's only read), the preview still catches DISABLE ROW LEVEL SECURITY, DROP POLICY and USING (true) from the SQL itself.
Preview from the dashboard
- Open the database, then Guard → Migration previews.
- Click Preview a migration, and paste the SQL (for MongoDB, its mongosh calls) or upload the file.
- Watch it run, then read the report.
The first preview restores a copy, which takes about as long as a restore test (Proof). For PostgreSQL, Rowsafe keeps that copy for an hour, so the next previews start in seconds, each on its own clone (one preview never sees another's changes). Other engines restore a new copy every time.
Preview from a terminal or CI
rowsafe preview app migrations/0042_add_reference.sqlThe report prints when the preview ends.
| Option | What it does |
|---|---|
--db NAME | The database to run it in, when the server has several and it isn't the one named like app |
--json | One object with verdict, summary, error (empty when the preview ran), markdown (a ready-made pull request comment) and result (every statement) |
--format markdown | Prints the pull request comment |
--fail-on dangerous (or careful) | Exits 3 at or above that verdict, and 2 when the migration fails: use it to stop a CI job. Without it, the command exits 0 once the preview ran, whatever the verdict, and 1 if it couldn't run |
- (instead of a file) | Reads the SQL from standard input |
In GitHub Actions, use the action's preview-sql (Save a Mark before every deploy).
AI agents use the preview_migration tool of the MCP server. It needs no write access: an API key and a local rowsafe mcp always have it; apps signed in with Rowsafe get it with Act for you. The Guard skill tells agents to preview every migration.
Without the agent
rowsafe preview postgres://user@host:5432/db FILE.sql (or a saved name) checks a PostgreSQL migration without the agent: on an empty copy of the schema in a temporary database on the same server when the connection's user may create databases, else by reading the SQL. Table sizes come from your database's statistics, so times are estimates, and errors that depend on your rows can't show. Same verdicts, options and exit codes; nothing on your database changes, and there is no restore point. See Check a migration first. On a server Rowsafe protects on its own, sudo rowsafe preview NAME FILE runs on a full copy restored from its backups, as here: see Rowsafe on your server.
Get your migration's SQL
Preview the SQL your tool would run, not its source file.
Create the migration without applying it, then preview its file:
npx prisma migrate dev --create-only --name add_reference
rowsafe preview app prisma/migrations/*_add_reference/migration.sqlOther engines
- The copy: latest backup plus every binary log since, on a private server with no network port.
- Statements run one by one, as MySQL and MariaDB run them. Schema changes commit one at a time, so a migration that fails halfway leaves earlier changes on production: the preview shows that as Dangerous.
- Locks are inferred (Rowsafe can't watch them on the copy): a statement that copies the table (a column type change,
ALGORITHM=COPY,OPTIMIZE TABLE) blocks writes for its whole run,LOCK=EXCLUSIVEblocks reads too, andALGORITHM=INSTANTorINPLACEtake only a brief lock. - Not run (marked in the report):
GRANT,CREATE USER,SET GLOBAL,LOAD DATA,INTO OUTFILE.
How it works, and its limits
- Where: on the database's server, at low CPU and IO priority, on no network port, with no background jobs (pg_cron doesn't run). Needs the agent running, at least one backup, and free disk: about 1.3 times the cluster's size plus 1 GB, plus room for a clone when a copy is reused.
- Freshness: at most about a minute behind production (ClickHouse: its newest backup). A copy is reused for up to an hour (
fresh_minutesin the API,--freshin the CLI). - Transactions: without its own
BEGIN/COMMIT, a migration runs in one transaction, so locks last until the end. Otherwise, or withCREATE INDEX CONCURRENTLYorVACUUM, statement by statement. psql commands (\set,\c) are skipped. - Never as a superuser (PostgreSQL): the migration runs as a regular role that owns your tables. Rowsafe runs
CREATE EXTENSIONfirst, as a superuser.ALTER SYSTEM, untrusted languages andCOPYto a file fail, and say why. - Times are estimates: the copy is usually slower, but on busy production a lock waits behind running queries, and every query behind it waits too. That's why Rowsafe suggests
lock_timeout. - What reaches Rowsafe: your SQL passes through and is deleted when the preview ends (only its size and a hash stay). The report holds table names, counts, sizes and timings. Values from your data in error messages show as
(a value from your data); the full message stays in the agent's log on your server. - Size: up to 960 kB of SQL, 5,000 statements and 30 minutes per preview, and five previews waiting per database.