| name | db-migrate-verify |
| description | Detect schema drift between SQLAlchemy models and the live Postgres — missing/extra columns, nullability mismatches, type mismatches. Reflects the models via a Python sidecar and diffs in TS. Read-only. Use as a pre-ship gate or when "the code says one thing, the DB says another". |
/db-migrate-verify
Single-backend skill. Calls rolepod_db_migrate_verify on the rolepod-dblab MCP server and surfaces the structured result. No fallback (D-001).
Does the live database actually match what the SQLAlchemy models declare?
Phase: Ship / Review. Read-only. The declared schema is reflected by a small Python sidecar (reflect_models.py) running in your project interpreter; the TS server owns the diff — the analog of how uiproof shells out to Appium for mobile.
When to use
- Pre-ship gate: confirm migrations actually applied and the DB matches the models.
- A bug smells like a code/DB mismatch (a column the model expects isn't there, or nullability differs).
- After a migration, to prove it landed with no drift.
When NOT to use
- Target is a WordPress site →
rolepod-wplab; dblab does not model WP schemas.
- Your ORM is not SQLAlchemy (Prisma / Drizzle / raw migrations) → not supported in v1; supply a
snapshot_path instead, or skip.
- You want to generate or design the schema → architect decision; dblab verifies, never designs (SPEC §3).
Inputs
conn — connection string (secret; never logged).schema (optional, default public).models_entrypoint — SQLAlchemy models as module:attr (a declarative Base or MetaData), e.g. app.models:Base.snapshot_path (optional) — fallback: a pre-generated normalized schema JSON, when the models can't be imported here.project_dir (optional) — directory the sidecar runs in so models_entrypoint imports (defaults to the server's working directory).
Native (models_entrypoint) is the primary path; snapshot_path is the fallback; if neither resolves, the result is unverifiable with a reason — never a false PASS, and the other four skills are unaffected.
Process
Call rolepod_db_migrate_verify:
{
"conn": "postgresql://…/db",
"schema": "public",
"models_entrypoint": "app.models:Base",
"project_dir": "/path/to/your/project"
}
Requires python3 + SQLAlchemy importable in project_dir (run rolepod-dblab doctor to check). If missing, pass snapshot_path instead.
Outputs
unverifiable — true if the models couldn't be reflected (with reason); status warn.passed — true iff no drift; drift[] — each: class (missing_table | extra_table | missing_column | extra_column | nullability_mismatch | type_mismatch), table, column?, expected (model), actual (db), detail.manifest_path (phase review, status pass / fail / warn).
Examples
Pre-ship drift gate
{ "conn": "postgresql://…/prod", "models_entrypoint": "app.models:Base", "project_dir": "/srv/app" }
passed: false with a missing_column on users.tier → a migration didn't apply; do not ship.
Evidence routing
- Standalone:
.rolepod-dblab/artifacts/db-migrate-verify_<ts>_<uuid>/
- With
rolepod parent (marker <git-root>/.rolepod/parent-active): <git-root>/.rolepod/evidence/<ts>-rolepod-dblab-db-migrate-verify/
The run directory holds drift.json + a manifest.json (Extension Protocol v1), so finish-work / review-code can use drift as a pre-ship gate.
If the tool is unavailable
The /db-migrate-verify skill needs the rolepod-dblab MCP server, which is not currently available. Confirm the plugin is installed and try again, or check that npx -y @rolepod/dblab is reachable.
