Declarative, SQL-first schema management built for the AI-agent era.
Schemorph is a CLI tool and library for managing database schemas as plain SQL files. You write the desired state of your database — tables, views, procedures — as ordinary CREATE statements. Schemorph computes what needs to change and applies it safely.
No ORM. No Visual Studio. No proprietary DSL. Just SQL, a single command, and output designed to be read by both humans and AI coding agents.
# Inspect a live database into SQL files
schemorph inspect --url "Server=...;Database=app" --out ./schema
# Preview what would change (never applies anything) — prints the plan and its fingerprint
schemorph diff --url "..." --schema ./schema
# Apply exactly the reviewed plan, or refuse if anything changed since the diff
schemorph apply --url "..." --schema ./schema --expect-plan <hash>
# Drift, ledger summary, pending migrations
schemorph status --url "..." --schema ./schema --migrations ./migrations
# Run as an MCP server (read-only tools + gated apply) for AI agents
schemorph mcpStatus: early (0.x), under active development. Released on NuGet and GitHub releases. Working today against SQL Server: the full loop (inspect / diff / apply / status) with destructive-change gating and semantic exit codes; programmable-object routing via CREATE OR ALTER; checksummed run-once migrations; a history ledger; brownfield adoption (existing databases and SSDT trees are consumed as-is — matching objects reconcile instead of re-applying); a versioned machine-readable plan format with per-change SQL and explanations, an apply gate (--expect-plan) and safety-lint warnings; and an MCP server (schemorph mcp) with schema/plan resources. The documents in docs/ define the project's anchors — see Design Principles for what is fixed and what is open.
On SQL Server, one combination of properties does not exist today as free, offline, login-free tooling: a declarative diff engine that treats procedures and functions as first-class, plus a versioned data-migration ledger, plus output an AI agent can act on safely. Every existing tool gives you some of these; none gives you all of them:
| Declarative diff | Procedures / functions as first-class | Versioned data migrations | CLI-first, no login | AI-agent-native output | |
|---|---|---|---|---|---|
| SSDT / SqlPackage | ✅ | ✅ | ❌ | ||
| EF Migrations | ❌ (code-first) | ❌ | ✅ | ❌ | |
| Flyway / Liquibase | ✅ | ✅ | |||
| Atlas | ✅ | ✅ | ❌ SQL Server driver is paid (Pro) and requires login | ||
| Bytebase | ❌ | ✅ | |||
| sqldef | ✅ | ❌ | ✅ | ❌ | |
| Schemorph | ✅ | ✅ | ✅ | ✅ | ✅ |
Competitive claims as of 2026-07; re-verified periodically as these tools evolve.
- Atlas gates its SQL Server driver behind a paid plan; Bytebase's declarative workflow is PostgreSQL-only; Flyway's schema model requires commercial editions; sqldef cannot manage procedures or functions; SSDT is bound to the Visual Studio project system.
- "AI-agent-native" here is not a roadmap bullet: plans are a versioned machine contract (plan-format.md),
applyexecutes only a reviewed plan fingerprint or refuses, and the same operations run as gated MCP tools — verified by an end-to-end agent harness on every integration run.
Schemorph is that combination: the declarative diff model (SSDT, Atlas, sqldef) and the versioned migration ledger (Flyway, Liquibase) in one coherent tool, with AI coding agents as a primary user rather than an afterthought.
Schemorph treats different kinds of database objects with the strategy that actually fits them, instead of forcing everything through one mechanism:
schema/ ← declarative: desired state, diffed automatically
tables/
views/
procedures/ ← idempotent: CREATE OR ALTER, re-applied on change
functions/
migrations/ ← versioned: ordered, checksummed, run once
V0001__seed_reference_data.sql
V0002__backfill_legacy_codes.sql
- Structural objects (tables, indexes, constraints) are diffed: Schemorph compares your SQL files against the live database and generates the
CREATE/ALTER/DROPplan. - Programmable objects (procedures, functions, views, triggers) are re-applied idempotently via
CREATE OR ALTER. Text-based diffing of procedure bodies is unreliable by nature; re-definition is not. This sidesteps an entire class of bugs that diff-only tools struggle with. - Data changes (seeds, backfills, one-off transformations) are versioned migrations tracked in a checksummed history ledger, Flyway-style. State diffing cannot express these; a ledger can.
See Architecture for the full model.
Every command supports structured output and safe-by-default semantics:
- Versioned plan format (docs/plan-format.md) — plans as machine contracts, with
--format jsonon every command; JSON is the default whenever stdout is redirected (agents pipe, humans get text) - The apply gate —
diffprints the plan's fingerprint (planHash);apply --expect-plan <hash>executes exactly the reviewed plan or refuses (plan_mismatch) if anything drifted in between diffis always a dry run; destructive operations require an explicit flag- Exit codes distinguish "no changes", "changes pending", and "error", and failures carry a typed
{kind, code, message, hint}envelope — see Errors and exit codes schemorph schemaprints a JSON manifest of the whole CLI surface (verbs, options, exit codes) so agents discover it without parsing help text- Credentials come from the
SCHEMORPH_URLenvironment variable (preferred over--url), and password material is redacted from every output channel — safe to pipe into logs and PR comments (there is a ready-made GitHub Actions recipe that posts the plan on every schema PR) schemorph mcpruns the same operations as an MCP server over stdio — read-only tools (schemorph_diff,schemorph_inspect,schemorph_status) plusschemorph_applygated behind a required plan fingerprint; the connection string stays in the server's environment, never in the conversation- Schema as context — the MCP server also exposes resources:
schemorph://schema(the live database as desired-state SQL, or one object viaschemorph://schema/{kind}/{name}) andschemorph://plan(the current plan with itsplanHash, ready for the apply gate; setSCHEMORPH_SCHEMA_DIRin the server environment), so hosts attach schema state directly instead of round-tripping tool calls - Agent Skill —
skills/schemorph/SKILL.mdpackages the procedural knowledge (the edit → diff → review → gated apply → converge loop, error-contract branching, migration immutability) in the Agent Skills format; drop it into your agent's skills directory
An AI agent manages a schema change end-to-end — inspect, plan, review, apply — without screen-scraping human-oriented output.
- SQL Server — initial target. The diff engine builds on DacFx (Microsoft's schema comparison framework, the same engine behind SSDT), giving full-fidelity handling of T-SQL objects from day one.
- PostgreSQL — planned. The provider boundary is designed in from the start; see ADR-0003.
dotnet tool install -g SchemorphStandalone self-contained binaries (win-x64, linux-x64, osx-arm64) are attached to each GitHub release — no .NET runtime required.
- Design Principles — the project's anchors; read this first
- Architecture — the three-strategy model, ledger, provider boundary
- The plan format — the machine-readable plan contract and its versioning
- Errors and exit codes — the typed error envelope agents branch on, and the safety-lint warning band
- Recipes — ready-made integrations (GitHub Actions plan-on-PR comment)
- Architecture Decision Records — why the foundational choices were made
See CONTRIBUTING.md. The project follows ADR-driven governance: significant design decisions are proposed and recorded as ADRs before implementation.
MIT. The core tool is and will remain free and fully functional offline — no accounts, no feature gates, no telemetry required for any local operation.