rolepod-dblab
Data-layer safety + truth verifier for AI coding agents. An MCP server that gives a coding agent eyes + safe hands on a live database: prove a migration applied, assert DB state as verify-evidence, read query plans, detect schema drift (code vs DB), and mutate data behind a transaction-confirm guard.
It is not a generic SQL client. Running ad-hoc SELECTs belongs to psql or an off-the-shelf Postgres MCP. dblab's value is the things nothing else does safely: guarded mutation, schema-drift detection, and DB state as PASS/FAIL evidence.
dblab is the data-layer limb of the rolepod ecosystem, alongside rolepod-uiproof (web/mobile UI) and rolepod-wplab (WordPress). v1 is Postgres-only.
The five tools / skills
| Skill | Tool | Phase | What it does |
|---|
/db-introspect | rolepod_db_introspect | Plan / Debug | Schema, columns, types, indexes, FK graph, row-count estimates → normalized snapshot. Read-only. |
/db-query | rolepod_db_query | Verify | Run a read-only query (inside BEGIN TRANSACTION READ ONLY) and return a structured PASS/FAIL assertion — not raw rows. |
/db-explain | rolepod_db_explain | Perf / Review | EXPLAIN [ANALYZE] → parsed plan flagging sequential scans and probable missing indexes. |
/db-migrate-verify | rolepod_db_migrate_verify | Ship / Review | Diff SQLAlchemy models vs live schema → drift report (missing/extra column, nullability, type mismatch). |
/db-write | rolepod_db_write | Build | Guarded mutation: preview → confirm → commit/rollback. The only tool that writes. |
The write-guard ritual (the differentiator)
db-write never writes without an explicit confirm. It holds a transaction open across tool calls:
- preview →
BEGIN, run the statement inside the transaction, return affected-row count + an optional before/after sample + a txn_id. Nothing is committed.
- confirm →
COMMIT (needs the txn_id).
- rollback →
ROLLBACK. An abandoned transaction auto-rolls-back after the idle timeout (default 5 min, ROLEPOD_DBLAB_TXN_IDLE_MS).
Holding a transaction open across turns is why dblab is an MCP plugin and not a prompt-only skill — a skill cannot enforce the confirm gate.
Quickstart (standalone)
dblab works in any MCP-capable CLI with just a connection string — no rolepod core required.
# Health check (Node, pg, python3 + SQLAlchemy for drift)
npx -y @rolepod/dblab doctor
# Smoke-test a connection
npx -y @rolepod/dblab test-connection "postgresql://user:pass@localhost:5432/mydb"
Register the MCP server (the repo ships per-CLI manifests):
- Claude Code / generic MCP:
.mcp.json → npx -y @rolepod/dblab
- Codex:
.codex-plugin/plugin.json
- Cursor:
.cursor-plugin/plugin.json
- Gemini CLI:
gemini-extension.json
pg is a hard dependency (every skill except drift needs it). python3 + SQLAlchemy are needed only for /db-migrate-verify; the other four skills work without them.
Schema drift (/db-migrate-verify)
The dblab server is TypeScript and can't import Python objects in-process, so it shells out to a tiny Python sidecar (reflect_models.py) that reflects your SQLAlchemy Base.metadata → JSON; the TS server owns the diff. This is the direct analog of how rolepod-uiproof shells out to Appium for the mobile runtime it can't reach natively.
// /db-migrate-verify
{ "conn": "postgresql://…/db", "models_entrypoint": "app.models:Base", "project_dir": "/path/to/project" }
Fallback modes: native (reflect the models) → snapshot (snapshot_path to a pre-generated JSON) → unverifiable (clear reason, never a false PASS).
Scope boundary (no-overlap)
dblab deliberately does not duplicate the rest of the ecosystem:
| Capability | Owner |
|---|
| Safe mutation (txn preview → confirm), schema drift, DB state as PASS/FAIL | dblab ✅ |
WordPress DB via WP semantics (options, transients, wpdb) | rolepod-wplab |
| Browser / native-mobile UI runtime | rolepod-uiproof |
| Schema design decisions | the architect agent (dblab verifies, never designs) |
| DB provisioning / scaling / backup | a cloud MCP (Railway / Vercel) |
Routing seam: target is a WordPress site → wplab; any other database (SaaS backend Postgres, analytics DB) → dblab.
Compose with rolepod (by reference, optional)
When the parent rolepod plugin is present (detected via the marker file <git-root>/.rolepod/parent-active), dblab routes evidence to <git-root>/.rolepod/evidence/ with a manifest.json per Extension Protocol v1. The composition is additive — dblab never blocks or caps anything; rolepod skills opt in:
