claude
A variant of Database Schema Migration Manager.
View the interactive variant page →
SchemaShift — Database Schema Migration Manager
An AI-native declarative database schema management platform that reduces migration risk through automated conflict resolution, impact analysis, and zero-downtime execution.
Supports PostgreSQL, MySQL and SQLite. The core is offline-first: planning, applying, drift detection and rollback need no network and no AI. AI features are a separate, opt-in package.
Contents
- Install · Quickstart · Configuration
- CLI reference · Exit codes
- Server + web UI · Development
- Documentation · Background
Install
Requires Node.js 20 or newer (22 LTS recommended).
npx schemashift --help # or: npm i -g schemashift
Quickstart
schemashift init --engine postgresql --dir migrations/
That writes schemashift.toml and a migrations/ directory. Add a migration, check what is
pending, then apply it:
# migrations/20260601_120000_init.sql
schemashift status --target local # lists it as pending
schemashift migrate --target local --yes # applies in timestamp order, records a checksum
schemashift status --target local # now applied, checksum_ok=true
Editing an already-applied migration is detected: the next migrate refuses to run and
names the altered version.
Prefer to describe the schema you want rather than the steps to get there:
schemashift plan --target local --declared schema.sql # preview; nothing is applied
schemashift migrate --target local --declared schema.sql --yes
schemashift plan --target local --declared schema.sql # empty — you are in sync
The full walkthrough, with the acceptance criteria each step satisfies, is in
specs/001-schema-migration-manager/quickstart.md.
It is executable — bash scripts/quickstart-acceptance.sh runs it end-to-end and asserts
every step.
Configuration
schemashift.toml describes where migrations live and how to reach each target.
Credentials are never stored in it — a target names a secret_ref that is resolved at
connect time (env:// is built in):
migrations_dir = "migrations"
[target.local]
engine = "postgresql"
secret_ref = "env://DATABASE_URL"
[target.production]
engine = "postgresql"
host = "db.example.com"
port = 5432
database = "myapp"
secret_ref = "env://PROD_DATABASE_URL"
SQLite targets point at a file instead:
[target.local]
engine = "sqlite"
file = "app.db"
Migration files
Files are <YYYYMMDD>_<HHMMSS>_<name>.sql and apply in timestamp order. A migration becomes
reversible by shipping its inverse alongside it as <version>.down.sql:
migrations/
20260601_120000_init.sql
20260603_090000_add_audit.sql
20260603_090000_add_audit.down.sql # makes it rollback-able
Without a down script a migration is treated as irreversible: rollback declines it rather
than risking data loss, and suggests a compensating migration instead.
CLI reference
Global options: --json for machine-readable output, -c, --config <path> to point at a
config other than ./schemashift.toml.
| Command | What it does |
|---|---|
init [--engine <e>] [--dir <d>] | Scaffold schemashift.toml and a migrations directory. |
status --target <t> | Show applied and pending migrations, and per-version checksum state. |
plan --target <t> [--declared <f>] | Preview pending changes without applying. With --declared, diff against a desired-state SQL file. |
migrate --target <t> [--declared <f>] [--to <v>] [--online] [--dry-run] [--yes] | Apply pending migrations in order, or apply a declarative plan. --online uses expand-contract where needed. |
drift --target <t> --declared <f> | Report divergence between the live database and a declared schema. Exits 1 when drifted, so CI can gate on it. |
check --target <t> [--declared <f>] [--allow-destructive] | CI safety gate. Fails on destructive operations unless explicitly sanctioned. |
rollback --target <t> (--last | --to <v>) [--yes] | Undo the most recent migration, or revert everything applied after a version. |
Exit codes
These are stable and intended for CI:
| Code | Meaning |
|---|---|
0 | Success — including "no drift" and "gate passed". |
1 | Operation failed, or a gate tripped: drift detected, tamper detected, or a rollback was declined as irreversible. |
2 | Usage error — unknown target, missing/conflicting flags, or a --to version not in the applied history. |
3 | check found a destructive operation that was not sanctioned with --allow-destructive. |
Example CI gate:
- run: schemashift check --target production --json
# exit 3 if a destructive op is present without --allow-destructive
Server + web UI
The governance layer — approval workflow, RBAC, impact analysis, audit trail and environment promotion — is optional and runs alongside the CLI:
docker compose -f docker/docker-compose.yml up # API + web + platform PostgreSQL
The API listens on port 8080. Auth, secrets and notifications ship with mock providers
behind pluggable interfaces, so the stack runs end-to-end before real ones are configured.
Four roles (viewer, author, reviewer, admin) enforce separation of duties on every
governed endpoint, granted per environment.
Development
npm install
npm run build # tsc --build across the workspace
npm test # vitest, 251 tests
npm run lint
npm run typecheck
The repo is an npm-workspaces monorepo:
| Package | Purpose |
|---|---|
packages/core | Engine adapters, DDL parsing, diffing, planning, safety classification, rollback. No network, no AI. |
packages/cli | The schemashift command. |
packages/server | Hono API, platform store (Drizzle/PostgreSQL), governance and drift monitoring. |
packages/web | React 19 + Vite UI. |
packages/ai | Opt-in AI: impact analysis and natural-language migration generation. Isolated so nothing else depends on it. |
Tests that need a real engine use testcontainers and require Docker; the rest run offline.
Documentation
- user-docs/ — getting started, installation, user guide and command reference, architecture, security & compliance, capability matrix (what is built vs. planned), and how the test suite is organised.
- specs/001-schema-migration-manager/ — spec, plan, data model, API/CLI contracts and the executable quickstart.
- collateral/ — go-to-market material: white papers, sales and marketing copy, and a self-contained one-page site.
Background and research
The problem, the opportunity, and the market context that motivated this project.
The problem
Database schema migrations are among the most dangerous operations in software delivery. Teams struggle with:
- Multi-team conflicts: Concurrent migration PRs from different teams collide without semantic understanding of what each change accomplishes
- Downstream impact blindness: Teams apply migrations without understanding which ORM models, queries, and application code reference affected columns
- Irreversible changes: Current tools cannot intelligently plan rollbacks for destructive DDL; risky changes lack forward-only safety guardrails
- Manual cross-database translation: Enterprises migrating between databases (MySQL → Postgres, Oracle → Aurora) face entirely manual translation of stored procedures, triggers, and proprietary SQL
- Drift creep: Schema drift (live database diverging from migration history) happens in production during hotfixes; no current tool correlates drift with root cause
The opportunity
- Automated conflict resolution in multi-team environments: Existing tools detect raw diff conflicts. An AI agent could analyze concurrent migration PRs, understand semantic intent (e.g., two teams renaming the same column differently), propose resolutions, and auto-merge safe changes — something no current tool addresses.
- Natural-language migration generation with safety analysis: Teams write risky migrations without realizing downstream impact. AI could parse the codebase, identify all ORM models and queries referencing an affected column, generate the safest migration path (expand-contract where needed), and explain trade-offs in plain language before apply.
- Intelligent rollback planning: Current rollback support is mechanical and often fails for irreversible DDL. AI could predict rollback feasibility at plan time, auto-generate compensating migrations, and recommend feature-flag-based forward-only strategies when rollback is unsafe.
- Drift root-cause analysis: Tools like Atlas can detect drift between declared and actual schema. AI could correlate drift events with deployment logs, hotfix commits, and database audit logs to identify exactly who, what, and why — enabling automated remediation rather than manual investigation.
- Cross-database migration translation: Enterprises migrating between databases face manual translation of proprietary SQL constructs, stored procedures, and triggers. AI could automate semantic translation with confidence scoring, flagging constructs requiring human review.
Market context
- Market size: $21.49B data migration (2025) → $23.98B (2026) → $47.74B (2032); database migration sub-segment growing at 19.6% CAGR
- Buyer personas: Platform/DevOps engineers, DBAs at regulated enterprises (finance, healthcare), backend developers at startups, SREs accountable for zero-downtime deployments
- Recent moves: Liquibase switched from Apache-2.0 to FSL in v5.0 (Sept 2025); Atlas/Ariga venture-backed; Bytebase (Y Combinator)
- Pricing landscape: Flyway free (OSS) to custom enterprise; Liquibase free → $20/user/month (Advanced) → custom Secure; Atlas Pro seat-based; Bytebase $20/user/month (Advanced)
Roadmap beyond today
Shipped today is the MVP plus most of the v1.1 governance layer. Still on the backlog:
- Kubernetes operator for GitOps-based schema management
- Cross-database migration translation (MySQL → PostgreSQL, Oracle → Aurora) with AI-assisted SQL conversion
- AI conflict detection for concurrent migration PRs from multiple teams
- SOC 2 / ISO 27001 tamper-evident audit trail for regulated industries
See user-docs/technical/capability-matrix.md for the precise built / opt-in / planned breakdown.
Research references
- Assunção et al. (2024): "Contemporary Software Modernization: Strategies, Driving Forces, and Research Opportunities" — peer-reviewed on modernization challenges
- ACM EASE (2025): "Seamless Data Migration between Database Schemas with DAMI-Framework" — empirical study on developer experience
- Atlas Blog (2024): "The Hard Truth about GitOps and Database Rollbacks" — practitioner perspective on rollback failure modes
- Liquibase FSL transition (Sept 2025): significant licensing shift signaling market maturation and consolidation pressure
Full research notes: initial-research/research.md and initial-research/features.md.