Database / Data Layer Template

Use this template when documenting database or data layer packages.

MANDATORY: Before using this template, analyze the current project to identify:

  1. Database type - Run: grep -r "postgres\|mysql\|sqlite\|mongo" package.json | head -3
  2. ORM/Query builder - Run: grep -r "prisma\|drizzle\|typeorm\|sequelize\|mongoose\|knex" package.json | head -3
  3. Schema files - Run: find . -name "schema.*" -o -name "*.sql" -o -name "*prisma*" | grep -v node_modules | head -5
  4. Migration system - Run: find . -name "*migration*" -type d 2>/dev/null
  5. Database config - Run: find . -name "*database*" -o -name "*db*" | grep -E "\.(js|ts|json)$" | head -5

Adaptive Template Structure

## Database
- Database: [DETECTED_DB_TYPE] ([PostgreSQL/MySQL/SQLite/MongoDB/etc])
- ORM/Query: [DETECTED_ORM] ([Prisma/Drizzle/TypeORM/etc])
- Schema: `[DETECTED_SCHEMA_PATH]` OR "Schema files not found"
- Migrations: `[DETECTED_MIGRATION_COMMAND]` OR "No migration system detected"
- Connection: via `[DETECTED_CONNECTION_FILE]` OR "Connection config not found"
- NEVER run migrations in tests

Detection Instructions

Schema Management (Adapt Based on Findings)

Prisma: Look for prisma/schema.prisma, npx prisma migrate Drizzle: Look for drizzle.config.ts, schema in src/db/ TypeORM: Look for entity files, typeorm migration:run Raw SQL: Look for .sql files, custom migration scripts MongoDB: Look for model definitions, no traditional migrations

Connection Management

Find actual connection patterns in the project:

  • Database URL in .env.example or config files
  • Connection pool configuration
  • Environment-specific database configs

Query Patterns (Copy from Existing Code)

Before documenting, find examples in the codebase:

  • How queries are written in this specific project
  • Transaction patterns actually used
  • Error handling approaches in place

Technology-Specific Adaptations

SQL Databases (PostgreSQL, MySQL, SQLite)

  • Migration commands and workflow
  • Schema definition files location
  • Seed data setup if present

NoSQL Databases (MongoDB, etc.)

  • Model/schema definitions
  • Index management approach
  • Data migration strategies (if any)

ORM-Specific Patterns

Copy patterns from existing code, don’t assume:

  • Entity/model definitions format
  • Query builder syntax actually used
  • Relationship definitions in place

Critical Warnings (Universal)

  • NEVER run migrations against production from local environment
  • NEVER commit database credentials or connection strings
  • NEVER run migrations in test suites (use test database setup)
  • NEVER assume database type - detect from project files

Anti-Patterns for Database Documentation

  • Don’t explain what databases or ORMs are in general
  • Don’t document SQL syntax basics
  • Don’t assume specific database technology without verification
  • Don’t duplicate ORM documentation that’s already available
Edit this page on GitHub