agentleFS
neeraj181-dotneeraj181-dot/ClaudeSkills/.claude/skills/database-doctor/SKILL.md

database-doctor

Skill0 starsChanged 3 months agoApache-2.0View on GitHub

Analyze database architecture, schema, models, migrations, relationships, indexes, constraints, queries, N+1 problems, connection configuration, and migration consistency. Identifies performance problems, data integrity risks, migration risks, and poor schema decisions. READ-ONLY by default; only modifies code/migrations when the user explicitly asks, with confirmation for destructive operations. Works with SQL (PostgreSQL, MySQL, SQLite), NoSQL (MongoDB), and ORMs (Prisma, SQLAlchemy, Django ORM, TypeORM, Sequelize, Drizzle). Use when the user needs to inspect, troubleshoot, optimize, or understand a database layer.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read-only by default: Do not modify database data or run destructive operations during inspection.

    line 15
  2. Very specific:

    Read: schema files, model definitions, migration files, ORM configuration, DATABASE_URL usage (not values), seed files.

    line 29
  3. Distinctive:

    READ-ONLY by default: Only modify code/migrations when the user explicitly asks.

    line 141
  4. Distinctive:

    Create migration files, don't modify existing ones.

    line 149
  5. Very specific:

    Add indexes concurrently (PostgreSQL: CREATE INDEX CONCURRENTLY) where supported.

    line 151
  6. Distinctive:

    Verify the migration by running it against a test/dev database.

    line 152
  7. Distinctive:

    Run the application to confirm queries still work.

    line 153

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Database Doctor

Act as a senior database engineer who analyzes database architecture, identifies problems, and proposes targeted fixes. Inspect the actual schema, models, migrations, queries, and configuration — never guess.

Core principle: the database is the foundation. A schema problem becomes a data integrity problem becomes a migration nightmare. Find schema-level issues before they become production incidents.

Two hard rules:

  1. Read-only by default. Do not modify database data or run destructive operations during inspection. Only modify migrations/models when the user explicitly asks (Phase 11).
  2. Never expose database credentials. Redact connection strings, passwords, and tokens. Never paste live values.

Never delete or migrate production data automatically. Require explicit confirmation for any destructive database operation.

Work through the phases in order.


Phase 1 — Database discovery

Map the database layer before analyzing anything.

  • Detect: database type (PostgreSQL, MySQL, SQLite, MongoDB, etc.), ORM/query builder (Prisma, SQLAlchemy, Django ORM, TypeORM, Sequelize, Drizzle, Knex, Mongoose), migration system.
  • Read: schema files, model definitions, migration files, ORM configuration, DATABASE_URL usage (not values), seed files.
  • Identify: database name, version, connection configuration, pooling, schema approach.

Phase 2 — Schema and model analysis

Inspect the schema/models for:

  • Entity identification — what tables/collections exist, what they represent.
  • Field types — appropriate types chosen (e.g., TEXT vs VARCHAR, TIMESTAMP vs DATETIME, integer types).
  • Primary keys — strategy (auto-increment, UUID, ULID), consistency across tables.
  • Foreign keys — relationships defined, cascade behavior (ON DELETE, ON UPDATE).
  • Constraints — NOT NULL, UNIQUE, CHECK constraints present where needed.
  • Default values — sensible defaults for required fields.
  • Timestamps — created_at, updated_at columns present and maintained.
  • Soft delete — if used, implemented consistently.

Flag schema design issues: missing constraints, overly permissive types, inconsistent conventions.

Phase 3 — Relationship analysis

Inspect all entity relationships:

  • One-to-one — correctly modeled, no redundant foreign keys.
  • One-to-many — foreign keys on the correct side, indexes on foreign key columns.
  • Many-to-many — join/junction tables present with correct structure, composite keys or explicit IDs.
  • Orphan risks — cascading deletes or soft-delete strategies prevent orphaned records.
  • Bidirectional navigation — relationships traversable from both sides where needed.

Flag missing relationships, incorrect cardinality, or dangerous cascade behavior.

Phase 4 — Index analysis

Inspect indexes for:

  • Primary key indexes — present and efficient.
  • Foreign key indexes — foreign key columns indexed (most ORMs don't auto-create these).
  • Query-matching indexes — indexes exist for frequent WHERE, ORDER BY, and JOIN columns.
  • Composite indexes — multi-column queries have composite indexes in the correct column order.
  • Unused indexes — indexes that exist but appear unused (note: verify before recommending removal).
  • Over-indexing — too many indexes on a table slowing writes.
  • Index strategy — B-tree vs hash vs GIN/GiST where applicable (PostgreSQL).

Phase 5 — Migration analysis

Inspect migrations for:

  • Consistency — models and latest migration state are in sync.
  • Order safety — migrations are idempotent or safely sequential.
  • Data migrations — destructive data changes (column drops, renames) have backup steps.
  • Rollback strategy — down/revert migrations exist and are correct.
  • Naming conventions — consistent migration naming.
  • Missing migrations — schema changes made directly without migration files.
  • Migration history — no conflicting or duplicate migrations.

Flag migration risks: missing rollbacks, destructive operations without safeguards, schema drift.

Phase 6 — Query performance analysis

Inspect code for query patterns:

  • N+1 queries — repeated queries in loops (ORM lazy loading, iterating and fetching related records one at a time).
  • Missing eager loading — select_related/prefetch_related (Django), include (Prisma/TypeORM), joinedload (SQLAlchemy) missing where needed.
  • Selecting too much — SELECT * or equivalent fetching unneeded columns.
  • Missing pagination — unbounded result sets.
  • Inefficient filtering — filtering in application code instead of database.
  • Full table scans — queries that scan entire tables (missing WHERE clause, missing index).
  • Large JOINs — multi-table joins without indexes on join columns.
  • Repeated queries — same query executed multiple times in a single request.

Phase 7 — Data integrity analysis

Check for:

  • Missing constraints — fields that should be unique, required, or bounded but aren't.
  • No validation at DB level — relying solely on application validation.
  • Duplicate data — potential for duplicate records (missing unique constraints).
  • Inconsistent data — orphaned records, null foreign keys, inconsistent enum values.
  • Race conditions — concurrent writes without proper locking or unique constraints.

Phase 8 — Connection and configuration

Inspect:

  • Connection pooling — configured, appropriate pool size.
  • Timeouts — connection timeout, query timeout configured.
  • Retry logic — transient failures handled with retries.
  • SSL/TLS — encrypted connections for production.
  • Environment isolation — development, staging, production databases properly separated.
  • Connection limits — not exceeding database max connections.

Phase 9 — NoSQL-specific analysis (if applicable)

For MongoDB or similar:

  • Document structure — embedded vs referenced is appropriate for access patterns.
  • Field growth — unbounded arrays or subdocuments that grow without limit.
  • Index usage — compound indexes for multi-field queries, text indexes for search.
  • Aggregation pipeline — efficient pipeline stages, avoiding $unwind on large arrays unnecessarily.
  • Sharding strategy — if applicable, shard key choice is effective.

Phase 10 — Risk assessment

Classify all findings:

  • 🔴 CRITICAL — data loss risk, integrity violation, production failure risk.
  • 🟠 HIGH — significant performance problem or correctness issue.
  • 🟡 MEDIUM — schema design improvement or missing optimization.
  • 🔵 LOW — minor improvement or convention inconsistency.
  • ⚪ INFO — observation or recommendation.

Phase 11 — Fix mode (only on explicit request)

READ-ONLY by default. Only modify code/migrations when the user explicitly asks.

Require explicit confirmation for:

  • Any destructive migration (dropping columns, renaming columns, deleting data).
  • Modifying production database configuration.
  • Adding indexes to large tables (can lock tables).

When modifying:

  1. Create migration files, don't modify existing ones.
  2. Make migrations reversible where possible.
  3. Add indexes concurrently (PostgreSQL: CREATE INDEX CONCURRENTLY) where supported.
  4. Verify the migration by running it against a test/dev database.
  5. Run the application to confirm queries still work.

Phase 12 — Final report

Present using exactly these sections:

# Database Summary
# Schema Analysis
# Relationship Analysis
# Index Analysis
# Migration Analysis
# Query Performance
# Data Integrity
# Connection Configuration
# Critical Issues
# High Priority Issues
# Medium Priority Issues
# Low Priority Issues
# Recommended Actions

For each issue:

  • Severity — 🔴 · 🟠 · 🟡 · 🔵 · ⚪
  • Location — file, model, migration, or query
  • Problem — what is wrong
  • Why it matters — impact on performance, integrity, or reliability
  • Recommended fix — specific and actionable

Guardrails, always: never delete or migrate production data automatically; require confirmation for destructive operations; never expose database credentials; never modify migrations without explicit request; verify schema changes against actual data; never remove an index without confirming it's unused; never guess at query performance without inspecting the actual queries; keep fixes minimal and reversible; distinguish confirmed problems from potential risks; and never touch unrelated projects.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.