10 Database Migration Anti-Patterns and What to Do Instead
Editing applied migrations, environment-specific scripts, ORM auto-DDL in production, untested rollbacks: ten habits that break deployments, with a fix for each.
Free while in early access
Database diagrams, drawn by running your migrations
Upload the migration files of Flyway, Liquibase, Prisma, Django or 18 other tools. SchemaDrawer runs them for real, in Docker, against the exact PostgreSQL, MySQL, MariaDB, SQL Server, Oracle or SQLite version you deploy to, and returns an SVG of the schema they produce.
22 migration tools
6 engines, 23 versions
SVG in seconds
GitHub Action included
In two minutes
Watch the idea, start to finish
Three migration files go in. A real database starts, the real tool runs them, the schema is read back and laid out. One SVG comes out, ready for your README, wiki or pull request.
The video is on its wayA two-minute walkthrough of the idea lands here soon. Until then, read how it works.
How it works
Three steps, no parser in sight
SchemaDrawer never guesses what your SQL means. It asks the database.
1
Upload the migration directory
One multipart request with your files, the tool, the engine and its version. The answer is a job id; a repeated request with the same Request-Id is never drawn twice.
2
The real tool runs on a real engine
A throw-away PostgreSQL, MySQL, MariaDB, SQL Server, Oracle or SQLite of the version you named starts in Docker. Flyway, Prisma, Django or whichever tool you use applies your files to it.
3
The schema is read back and drawn
Tables, columns, types, primary and foreign keys come straight from the engine's metadata, get laid out by a graph layout engine and are rendered as a crisp SVG. The link stays valid for an hour.
$ curl -X POST https://schemadrawer.com/api/v1/drawing \ -H "Request-Id: $(uuidgen)" -F "userId=5f0c1d2e-..." \ -F "migrationType=FLYWAY" -F "databaseType=POSTGRESQL" -F "version=18" \ -F "files=@db/migration/V1__create_owners_and_pets.sql" \ -F "files=@db/migration/V2__create_vets.sql" \ -F "files=@db/migration/V3__create_visits.sql" {"jobId":"0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f"} $ curl https://schemadrawer.com/api/v1/drawing/0b6e2f4c-8d1a-4c3e-9f7a-2a5b6c7d8e9f {"status":"SUCCESS","diagramUrl":"https://.../diagram.svg"} # 6 seconds later
Why run instead of parse
A migration is defined by what the tool does with it
Static parsers and model diffs approximate your schema. Running the migration on the engine you deploy to shows the schema you will actually get.
| Situation | Parse the SQL | Diff the ORM models | Run the migrations SchemaDrawer |
|---|---|---|---|
| Migrations written in code (Django, EF Core, Rails, Knex, Alembic) | Nothing to parse | Shows the model, not what was migrated | The tool executes them |
| Dialect-specific DDL and vendor types | One grammar per dialect, always behind | Depends on the ORM's mapping | The engine decides |
| Procedural blocks, conditional SQL, DO blocks | Skipped or misread | Invisible | Executed like everything else |
| Renames, drops and alterations across many files | Needs a simulator | Only the end state, if in sync | Applied in order, end state read back |
| Differences between engine versions | One grammar fits all | Ignored | Pick the version, PostgreSQL 10 to 18 |
| A broken migration | Best-effort error | Not detected | The tool's own error message |
Supported migration tools
22 tools, every ecosystem
Each tool runs in its own container image, in its real version. Pick yours to see what to upload.
RustDiesel
Supported databases
6 engines in 23 versions
Draw on the version you actually deploy to. Every combination of tool and engine is part of SchemaDrawer's own test suite.
GitHub Action
A diagram that updates itself
Add one step to a workflow. On every change to your migrations the action uploads them, waits for the diagram and opens a pull request with the new SVG. Identical output, no pull request.
- Runs on
ubuntu-latestwith nothing to install - Fails the job with the migration tool's message when a migration is broken
- Retries are safe: a run attempt is never drawn twice
name: Update schema diagram
on:
push:
branches: [main]
paths: ['db/migration/**']
workflow_dispatch:
permissions:
contents: write
pull-requests: write
jobs:
draw:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: schemadrawercom/action@v1
with:
sql-directory: db/migration
output-path: docs/schema-diagram.svg
migration-type: FLYWAY
database-type: POSTGRESQL
database-version: '18'
github-token: ${{ secrets.GITHUB_TOKEN }}
Example
Thirteen tables, one request
An e-commerce schema in four Flyway migrations, drawn on PostgreSQL 18. Types are the ones PostgreSQL reports; arrows carry the foreign-key column.
More examples: the same schema in ten tools and on six engines
Pricing
Free today. Enterprise when you need it.
No account, no card, no limits beyond the size of an upload. Enterprise plans for teams that need self-hosting, SSO and guarantees are on the way.
Available now
Free
$0
For every developer and every project, while we build it.
- All 22 migration tools and 23 engine versions
- Uploads up to 100 MB and 2000 files
- HTTP API and GitHub Action
- SVG output you own
Coming soon
Enterprise
Let's talk
For teams with compliance, scale and support needs.
- Self-hosted or private cloud
- SSO, audit log, retention controls
- Priority queue and SLA
- Bigger uploads, longer timeouts, support
FAQ
Questions, answered
Everything else is in the docs, or an email away.
No. Every drawing starts a fresh, empty database container of the engine and version you name, runs your migrations in it, reads the schema back and destroys the container. Nothing connects to your systems.
The migration directory exactly as your tool keeps it: Flyway's SQL scripts, Liquibase's changelog tree, Prisma's migrations folder, Django's app directories, EF Core's Migrations folder and so on. Each tool page describes the expected layout.
Every table the migrations create, with its columns and their type names, primary keys in bold, foreign keys marked FK and drawn as labelled arrows between tables. The migration tool's own history table is left out. Views, indexes, check constraints, defaults, comments and data are not drawn.
Usually a few seconds once the images are warm: the PetClinic sample on PostgreSQL 18 took about six seconds end to end in our runs, most of it database start-up. SQL Server and Oracle take longer to start, and the first drawing with a rarely used tool can take longer still. A drawing is stopped after 120 seconds.
The job ends with status ERROR and the migration tool's own output, exit code included, so you see the same message you would see on your machine.
Not yet. SchemaDrawer is an HTTP API with a GitHub Action on top; the Swagger UI at schemadrawer.com/swagger-ui.html lets you try a drawing from the browser.
Yes, everything is free today, with uploads of up to 100 MB and 2000 files per drawing. Enterprise plans with self-hosting, SSO, SLAs and bigger limits are planned; any change to the free offer will be announced well ahead of time.
Yes. The API is plain HTTP with multipart uploads, so curl, any CI system and any language work. The GitHub Action is a bash script around the same two calls.
From the blog
Migrations, diagrams and databases
Practical writing on schema design, migration tools and keeping documentation honest.
Zero-Downtime Database Migrations: The Expand and Contract Pattern
How to change a live schema without an outage: expand, backfill in batches, switch reads and writes, then contract. With safe NOT NULL, renames and lock timeouts.
Testing Database Migrations in CI with Docker and Testcontainers
Run migrations against a throw-away real database on every change: a Testcontainers and Flyway example, CI service containers, version matrices and schema checks.
Draw your schema in the next five minutes
One HTTP call with your migration files, one poll, one SVG. Free while we build it.