Database Agent

Your senior DBA — real database connections, real work, not just file writes

What it does

Connects to your real database and reads its actual state before touching anything. Designs schemas with correct types, foreign keys, and indexes. Authors zero-downtime migrations with full rollback SQL. Finds and eliminates slow queries with EXPLAIN ANALYZE. Tunes performance by identifying bloat, missing indexes, and connection pressure. When an incident hits, pinpoints blocking locks, identifies connection exhaustion, and prescribes the exact pg_terminate_backend call to recover. Writes everything to GitHub as migration files if no database is connected.

What it can do

Live Schema Introspection

Connects to your actual PostgreSQL database and reads the real schema state before designing anything. Enumerates all tables with row count estimates, describes every column (type, nullable, default), maps all foreign key relationships, lists every index with its size and definition, and reads pg_stat_user_tables for live access patterns (seq vs index scans). Designs are grounded in what is actually there, not guessed.

“Connect to our database and give me a complete picture of the current schema before we plan the migration”
“Map all the foreign key relationships in our database — I need to understand the data model”
“Read our schema and tell me which tables have the most missing indexes based on actual usage”

Schema Design

Designs PostgreSQL schemas that follow production-proven patterns: UUID primary keys for distributed systems, TIMESTAMPTZ everywhere (never TIMESTAMP), soft deletes with deleted_at TIMESTAMPTZ NULL and a partial index on WHERE deleted_at IS NULL, JSONB only when structure genuinely varies per row, proper ON DELETE semantics (CASCADE, SET NULL, or RESTRICT — never implicit). Every foreign key, check constraint, and unique constraint is reasoned from the business rules.

“Design a multi-tenant SaaS schema: organizations, users, roles, memberships, and audit log”
“Design the schema for a marketplace: buyers, sellers, listings, orders, reviews, payments”
“I need a notifications system — design the schema to support email, push, and in-app types”

Zero-Downtime Migration Authoring

Writes numbered migration files (001_description.sql) with UP and DOWN sections. Applies zero-downtime patterns for large production tables: adds NOT NULL columns with a DEFAULT first, then backfills, then sets NOT NULL in a separate migration. Always uses CREATE INDEX CONCURRENTLY (never blocking production). Never drops a column in the first migration — renames to _deprecated_name first, removes in a follow-up after code is deployed.

“Write a zero-downtime migration to add email_verified to the users table — it has 2M rows”
“Create migration files to rename the `customers` table to `clients` across the entire schema without downtime”
“Write the migration to add a composite index on (user_id, created_at DESC) to the events table”

Query Optimization

Runs EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) on your slow query and reads the full plan. Identifies Seq Scans on large tables, missing indexes, inefficient join order, and bad row estimates caused by stale statistics. Chooses the correct index type for the access pattern: B-tree for equality/range, GIN for JSONB/full-text/array, partial index when a WHERE clause filters most rows. Creates the index CONCURRENTLY, reruns EXPLAIN, and reports the before/after cost and actual milliseconds.

“This query is taking 3 seconds on a 500K row table — analyze it and add the right index”
“Find all the queries being run without indexes and fix the worst offenders”
“Our dashboard endpoint is slow — run EXPLAIN ANALYZE on the query and optimize it”

Performance Tuning

Runs a full performance audit: reads pg_stat_user_tables to find tables with high seq_scan relative to idx_scan, reads pg_stat_statements to identify the slowest queries by mean execution time, reads pg_database_size and per-table dead_ratio to find bloat, and reads pg_stat_activity to identify long-running queries and connection pressure. Takes action: runs VACUUM ANALYZE on bloated tables, creates missing indexes, and writes a tuning report.

“Run a full performance audit of our database and give me a prioritized list of what to fix”
“Our database has been getting slower over time — find the cause and tune it”
“Identify which tables need VACUUM ANALYZE and run it — our dead row counts are climbing”

Crash Recovery & Incident Response

When a live incident hits, reads pg_locks joined to pg_stat_activity to find exactly which PID is blocking and what query it is running. Reads pg_stat_activity to detect connection exhaustion, idle-in-transaction sessions eating connections, and long-running queries. Prescribes the exact pg_cancel_backend or pg_terminate_backend call to unblock the system. Checks replication lag. After recovery, runs VACUUM ANALYZE on affected tables and writes a root cause summary.

“We have a production incident — queries are hanging. Find the blocking lock and tell me how to recover”
“Our connection pool is maxed out and the API is failing. Find what's eating connections”
“The database just recovered from a crash — run a full health check and vacuum all affected tables”

ORM Schema Generation

After designing or introspecting the schema, generates the corresponding ORM schema file: Drizzle ORM (TypeScript), Prisma schema (schema.prisma), or SQLAlchemy models (Python). Schema is generated from the real database structure or the SQL migration files — not written by hand from vague descriptions. Works as the next step after any schema design or migration task.

“Introspect our database and generate the Drizzle ORM schema file for it”
“Generate a Prisma schema from the migration files we just wrote”
“Convert our existing raw SQL schema to SQLAlchemy models for our Python API”

Good for / not for

Great for

Designing schemas for new features that need to be correct the first time
Writing zero-downtime migrations for large production tables
Finding and fixing slow queries that are hurting application performance
Running a performance audit before a traffic spike or scaling event
Live incident recovery — identifying and clearing database locks
Generating ORM schema files that match the real database structure
Understanding the current schema state before a major refactor

Not the right fit for

MySQL or MongoDB (PostgreSQL only)
Database provisioning and hosting setup (that's the Backend or Infrastructure Agent)
Application-layer ORM query optimization (it can explain the SQL, but not rewrite your ORM calls)
Databases that don't expose a direct connection string (managed proxies with no direct access)

Example tasks

“Connect to our production database, inspect the current schema, and design the tables needed for a multi-tenant billing system with proper foreign keys, indexes, and migration files”
“This query is taking 4 seconds — analyze it with EXPLAIN ANALYZE, add the right indexes, and verify the speedup”
“Run a full performance audit: identify tables with bloat, find slow queries from pg_stat_statements, and produce a tuning report with specific recommendations”
“We have a live incident — the API is hung and I think there's a database lock. Find the blocking query, identify which session is holding it, and recover the database”
“Write zero-downtime migration files to add a deleted_at soft-delete column and backfill existing rows without locking the users table”