Migration Guardian

An AI agent that reviews PostgreSQL migrations against real database state, tests them safely in a sandbox, and blocks risky changes before they reach production.

Comment

Inspiration

Database migrations are one of the deployment steps I treat most carefully as a backend engineer.

A migration can work perfectly against a fresh development database and still fail in production because of schema history, existing data, constraints, indexes, dependencies, or drift.

Migration Guardian came from a simple idea: production should not be the first place a migration is tested against real database state.

What it does

Migration Guardian is an AI-powered PostgreSQL migration safety agent that reviews database changes before deployment.

It can accept raw SQL, Django migrations, and Alembic revisions. It inspects the current database in read-only mode, gathers relevant evidence, reconstructs the required schema in an isolated PostgreSQL environment, executes the candidate migration safely, and returns an evidence-backed decision:

BLOCK · APPROVE WITH CONDITIONS · APPROVE

The V1 is usable through a deployed web application, REST API, and local CLI.

How we built it

Migration Guardian is built with Python, FastAPI, PostgreSQL, the Strands Agents SDK, and OpenAI.

Strands powers the migration review workflow and structured assessment. Deterministic components first identify affected database objects and collect targeted evidence such as schema state, NULL counts, duplicate values, constraints, and migration execution results.

The agent then reasons over that bounded evidence instead of receiving an entire database catalog.

Candidate migrations never execute against the source database. The source remains read-only while execution and post-migration verification happen in an isolated PostgreSQL environment.

The API uses an asynchronous review flow, while the same review capability is also exposed through the migration-guardian CLI.

Challenges we ran into

One of the hardest problems was distinguishing a migration failure from a Migration Guardian failure.

If PostgreSQL rejects a migration because a column already exists or a relation is missing, that is valuable evidence that should become a verified blocker—not an internal server error.

Agent reliability was another challenge. Structured responses initially required several iterations of tighter schemas, clearer prompts, and better tool boundaries before the Strands workflow consistently produced the assessment shape the product needed.

I also hit a major context-efficiency problem. An early implementation sent almost the entire database catalog to the model; one small migration consumed more than 45,000 input tokens. By identifying affected objects first and collecting only relevant evidence, we reduced that review context by more than 95%.

Accomplishments we're proud of

Migration Guardian does more than statically inspect migration code.

It combines:

  • actual database-state inspection;
  • targeted read-only evidence;
  • isolated migration execution;
  • PostgreSQL error and SQLSTATE evidence;
  • post-migration verification;
  • structured deployment decisions;
  • support for SQL, Django, and Alembic migrations;
  • web, API, and CLI access.

The result is a migration review that can explain not only that something looks risky, but why it is risky based on actual database evidence.

What we learned

The biggest lesson was that migration safety is fundamentally a state problem, not just a code-analysis problem.

The same migration can behave differently across databases because of data distributions, schema history, constraints, and dependencies.

I also learned that agents are most useful here when deterministic software gathers the facts first. The model should reason over explicit, attributable evidence rather than act as an oracle over an unrestricted database.

That principle shaped the product:

deterministic tools gather facts; the agent makes the engineering judgment.

What's next

The current V1 already supports web, API, and local CLI workflows.

Next, I want to make Migration Guardian fit even more naturally into the software delivery lifecycle through:

  • first-class GitHub Actions and GitLab CI deployment gates;
  • PyPI distribution;
  • pre-commit integration;
  • multi-file and migration-chain analysis;
  • migration-history awareness;
  • additional frameworks such as Flyway, Liquibase, Laravel, Rails, Prisma, and others;
  • broader database-engine support;
  • an MCP interface for coding agents and IDEs;
  • a future Database Doctor mode for proactively identifying database risks before a migration is even written.

The long-term goal is simple:

catch migration failures before production becomes the test environment.

Built With

Share this project:

Updates

Submission history