Database Migration Toolkit

Database Migration Toolkit

A dependency-free, runnable toolkit for changing database schemas the safe way:

versioned up/down migrations, a tiny SQL runner you can actually read, and the

expand/contract patterns that let you ship schema changes to a busy database **without

downtime**. Everything here runs on the Python standard library and SQLite out of the box —

no pip install, no services to start — and the same patterns scale up to production

PostgreSQL and MySQL.

This is not another opaque migration framework. It's a small runner plus a set of worked,

proven examples and field-tested documentation, so you can learn the patterns and lift

the code.

Why this exists

The SQL in a schema migration is rarely the hard part. The hard parts are:

• Two code versions hit the database at once during a rolling deploy — the schema has

to be valid for both.

• A single ALTER or UPDATE can lock or rewrite a huge table and stall production.
• Rolling back is often impossible (data's gone) or unsafe (DDL auto-commits on MySQL).
• Teams collide on version numbers and silently edit already-applied migrations.

This toolkit gives you a concrete, working model for all four, with the trade-offs written

down.

Features

• runner/migrate.py — a ~480-line, stdlib-only migration runner: ordered

up/down, a schema_migrations tracking table, SHA-256 checksums that detect a

changed-after-apply migration, status, validate, and a new scaffolder. Each

migration runs in one transaction.

• Drives 3 engines through one thin seam: SQLite with zero setup (default), plus

PostgreSQL and MySQL by passing a --url (install that driver).

• A proven expand/contract example — four bundled migrations that split a full_name

column into first_name/last_name with zero downtime, fully reversible end to end.

• Production PostgreSQL DDL — the same change with CREATE INDEX CONCURRENTLY-class

concerns, a transition trigger, a batched backfill procedure, and the lock-light

NOT NULL technique.

• A reusable batched-backfill template (PostgreSQL + MySQL) using keyset pagination.
• Six field guides covering versioning, zero-downtime expand/contract, online schema

change per engine, the rollback playbook, large-table backfills, and a cross-engine

cheat sheet — plus a reviewer's checklist for migration PRs.

What's inside

database-migration-toolkit/
├── README.md
├── LICENSE
├── runner/
│   └── migrate.py                       # the stdlib migration runner (CLI)
├── migrations/                          # runnable on SQLite with zero setup
│   ├── V001__create_core_schema.up.sql / .down.sql
│   ├── V002__add_indexes.up.sql / .down.sql
│   ├── V003__expand_split_customer_name.up.sql / .down.sql   # EXPAND
│   └── V004__contract_drop_full_name.up.sql / .down.sql      # CONTRACT
├── examples/
│   ├── backfill_batched.sql             # reusable keyset-batched backfill (PG + MySQL)
│   └── postgres_expand_contract/        # the production-grade PostgreSQL version

*... continues with setup instructions, usage examples, and more.*