MigrationGuard

MigrationGuard Dashboard — Submit and analyze database migrations through the autonomous safety verification pipeline.
Autonomous Verification Pipeline — Tracks shadow database creation, migration execution,deterministic validation, AI diagnosis,and retesting
End-to-end verification: PostgreSQL detects the failure, Gemini diagnoses it, and MigrationGuard re-tests the fix in a fresh shadow DB.
End-to-end verification: PostgreSQL detects the failure, Gemini diagnoses it, and MigrationGuard re-tests the fix in a fresh shadow DB.
Detailed Verification Report — PostgreSQL evidence, deterministic safety checks, Gemini diagnosis, and independently re-tested remediation.
Detailed Verification Report — PostgreSQL evidence, deterministic safety checks, Gemini diagnosis, and independently re-tested remediation.
Detailed Verification Report — PostgreSQL evidence, deterministic safety checks, Gemini diagnosis, and independently re-tested remediation.

MIGRATIONGUARD

AI-powered database migration safety agent that actually executes migrations against disposable PostgreSQL shadow databases, validates the result deterministically, and re-tests AI-generated fixes before declaring them safe.

THE PROBLEM

Database migrations can be syntactically correct but still fail when executed against a database containing real, existing data.

For example:

ALTER TABLE users ADD COLUMN ssn VARCHAR(11) NOT NULL;

This SQL is valid, but PostgreSQL rejects it when existing users are present because the new NOT NULL column would initially contain NULL values.

Developers commonly depend on static migration linters, manual staging environments, or code review. These approaches can miss runtime failures caused by the actual state of the database.

We wanted to build something that doesn't just read the migration — it actually tests it.

OUR SOLUTION

MigrationGuard is an autonomous AI database migration safety agent that executes proposed migrations inside disposable PostgreSQL shadow databases before they reach production.

The workflow is:

Analyze the proposed migration for risky operations.
Create an isolated disposable PostgreSQL shadow database.
Seed it with representative schema and data.
Capture the database state before migration.
Execute the proposed migration.
Run deterministic safety checks against the resulting database.
Produce a GO, WARN, or NO-GO verdict.
If the migration fails, Google Gemini diagnoses the root cause.
Gemini generates a staged remediation.
MigrationGuard creates a fresh shadow database.
The remediation is executed and validated again.
The final result is returned with an auditable evidence trail.

CORE DESIGN PRINCIPLE

AI can recommend a fix, but AI cannot declare a migration safe.

PostgreSQL execution and deterministic validation are the safety authority.

REAL DEMONSTRATION

We tested MigrationGuard with:

ALTER TABLE users ADD COLUMN ssn VARCHAR(11) NOT NULL;

The disposable shadow database contained existing user records.

PostgreSQL rejected the migration with:

column "ssn" of relation "users" contains null values

MigrationGuard produced:

NO-GO

Gemini then diagnosed the problem and generated a staged remediation:

ALTER TABLE users ADD COLUMN ssn VARCHAR(11);

UPDATE users SET ssn = 'UNKNOWN' WHERE ssn IS NULL;

ALTER TABLE users ALTER COLUMN ssn SET NOT NULL;

MigrationGuard did not blindly trust the AI-generated SQL.

Instead, it created a brand-new shadow database, executed the remediation, and ran the deterministic validation suite again.

The remediation passed the verification pipeline and received:

GO

UNKNOWN is only a demonstration placeholder. A real production migration involving sensitive information would require a domain-appropriate and secure backfill strategy.

DETERMINISTIC SAFETY ENGINE

MigrationGuard uses six deterministic safety checks:

Execution Checks whether PostgreSQL successfully executes the migration.
Schema Diff Checks whether tables and columns changed unexpectedly.
Row Counts Checks for unexpected data loss.
NULL Violations Checks whether new constraints introduce invalid NULL values.
Constraints Checks whether foreign keys and other constraints remain valid.
Index Presence Checks whether important indexes are preserved.

These checks provide the authoritative safety decision.

THE AI LAYER

Google Gemini is used for:

Understanding PostgreSQL runtime errors
Explaining root causes
Suggesting safer migration strategies
Generating multi-step remediation SQL

Gemini cannot override deterministic safety failures.

The system follows:

AI proposes → PostgreSQL executes → Deterministic validators decide

WHY MIGRATIONGUARD IS DIFFERENT

Static migration linters can analyze SQL but generally cannot execute it against realistic existing data.

Manual staging can execute migrations but requires manual setup and verification.

LLM code review can suggest fixes but cannot prove that those fixes actually work against a database.

MigrationGuard combines:

Real PostgreSQL execution + Deterministic safety validation + Agentic AI remediation + Automatic re-testing

The key difference is that an AI-generated fix is not considered safe simply because the AI generated it. The fix must survive another real PostgreSQL execution and validation cycle.

HOW WE BUILT IT

Frontend: React 18, TypeScript, Vite, and Tailwind CSS.

Backend: Python 3.11+, FastAPI, Uvicorn, SQLAlchemy, and PostgreSQL.

AI and Agent: Google Agent Development Kit (ADK) and Google Gemini.

Database: PostgreSQL with disposable shadow databases and representative seed data.

Deployment: Multi-stage Docker application containing the React frontend and FastAPI backend, deployed as a live web application.

ARCHITECTURE

Developer ↓ React Dashboard ↓ FastAPI Backend ↓ Migration Orchestrator ↓ Disposable PostgreSQL Shadow Database ↓ Migration Execution ↓ Deterministic Validation ↓ GO / WARN / NO-GO ↓ If Failure ↓ Google ADK + Gemini ↓ Remediation SQL ↓ Fresh Shadow Database ↓ Re-verification ↓ Final Verdict and Evidence

WHAT WE LEARNED

Our biggest lesson was that valid SQL does not necessarily mean a safe migration.

We also learned that AI-generated code should not automatically be trusted when database integrity is involved.

Gemini is useful for understanding errors and generating remediation strategies, but generated SQL still needs to be executed and verified.

This led us to design MigrationGuard around a strict separation:

AI proposes → PostgreSQL executes → deterministic validators decide.

CHALLENGES WE FACED

The hardest engineering challenges included:

Creating and destroying disposable PostgreSQL databases safely.
Reproducing realistic database states using representative seed data.
Detecting schema and data integrity changes after migrations.
Handling PostgreSQL runtime failures rather than relying only on SQL parsing.
Preventing AI-generated remediation from bypassing safety checks.
Re-testing remediation against a completely fresh shadow database.
Maintaining an auditable evidence trail for every decision.
Deploying the React frontend and FastAPI backend together in a single production container.

TESTING

MigrationGuard includes an automated test suite covering validators, agent tools, orchestration, security policies, API routes, and AI integration.

51 tests passed successfully.

LIVE DEMO

Live Application: https://migrationguard.onrender.com

API Documentation: https://migrationguard.onrender.com/docs

Health Check: https://migrationguard.onrender.com/health

Source Code: https://github.com/prathampoojari13/MigrationGuard

WHY WE BUILT IT

Database migrations are often treated as simple code changes, but they can directly affect application availability and data integrity.

Instead of asking:

Does this SQL look correct?

MigrationGuard asks:

What actually happens when this SQL runs against an existing database?

If the migration fails, MigrationGuard uses AI to help find a solution and then tests that solution again before recommending it.

That combination of real database execution, deterministic safety checks, agentic remediation, and empirical re-verification is the core idea behind MigrationGuard.

WHAT'S NEXT

Future improvements include:

Automated production schema introspection using privacy-preserving snapshots.
PostgreSQL lock and migration-duration analysis.
GitHub CI/CD integration for automatic migration verification.
More sophisticated data-aware backfill strategies.
Support for increasingly complex migration patterns.
Expanded database engine support.

SAFETY DISCLAIMER

MigrationGuard evaluates migrations inside isolated shadow PostgreSQL environments using representative seed data.

It does not replace production backups, staging environments, database review, or organizational deployment procedures.

Real production workloads can introduce race conditions, lock contention, large-data performance issues, and data distributions that are not represented in the shadow dataset.

Generated remediation should always be reviewed before production use.

Never copy unmasked sensitive customer data into a shadow environment.

TEAM

Pratham Poojari

Built for the All Things Agentic 2026 Hackathon.