Db Docs

Automatically generate comprehensive database documentation including ERD diagrams, table relationships, column descriptions, indexes, triggers, stored procedures, and interactive HTML documentation from your existing database schemas across multiple database engines.

When to Use This Command

Use /db-docs when you need to:

• Document existing database schemas for team onboarding
• Generate ERD diagrams for architectural reviews
• Create data dictionaries for compliance requirements
• Build interactive database documentation websites
• Document relationships and foreign key constraints
• Generate migration guides between schema versions
• Create developer reference documentation
• Export schema documentation for audits
• Build database catalogs for data governance
• Generate test data documentation

DON'T use this when:

• Database is still in early design phase (use /design-schema instead)
• You only need query optimization docs (use /optimize-query)
• Working with NoSQL databases without fixed schemas
• Database has no meaningful structure to document

Design Decisions

This command implements SchemaSpy with PlantUML as the primary approach because:

• Supports 30+ database types out of the box
• Generates interactive HTML with JavaScript navigation
• Creates high-quality vector ERD diagrams
• Analyzes implicit relationships via naming conventions
• Produces detailed table and column documentation
• Open-source with active community support

Alternative considered: dbdocs.io

• Cloud-based with collaboration features
• DBML (Database Markup Language) based
• Requires internet connection
• Recommended for team collaboration needs

Alternative considered: SQL Server Data Tools

• Excellent for SQL Server specifically
• Visual Studio integration
• Platform-specific limitation
• Recommended for pure Microsoft stacks

Prerequisites

Before running this command:

1. Database connection credentials with schema read access
2. JDBC driver for your database type
3. Java Runtime Environment (JRE) 8+
4. GraphViz installed for diagram generation
5. Sufficient disk space for generated documentation

Implementation Process

Step 1: Database Introspection

Connect to database and extract complete schema metadata including tables, views, procedures, and relationships.

Step 2: Relationship Analysis

Identify explicit foreign keys and implicit relationships based on naming patterns and data types.

Step 3: ERD Generation

Create entity-relationship diagrams at multiple levels: full schema, per-module, and neighborhood views.

Step 4: Documentation Generation

Generate HTML documentation with search, filtering, and interactive navigation features.

Step 5: Export and Publishing

Package documentation for distribution via static hosting, PDF export, or integration with existing docs.

Output Format

The command generates:

• index.html - Main documentation entry point
• diagrams/ - ERD diagrams in multiple formats
• schema.svg - Complete database diagram
• relationships.png - Relationship overview
• tables/*.svg - Individual table diagrams
• tables/ - Individual table documentation
• columns.html - Searchable column index
• constraints.html - All constraints documentation
• routines.html - Stored procedures/functions
• orphans.html - Tables without relationships
• anomalies.html - Schema issues and warnings
• metrics.json - Database metrics and statistics

Code Examples

Example 1: Comprehensive Database Documentation Generator

// database-doc-generator.js
const { exec } = require('child_process');
const fs = require('fs').promises;
const path = require('path');
const mysql = require('mysql2/promise');
const { Client: PgClient } = require('pg');
const oracledb = require('oracledb');
const sql = require('mssql');
const ejs = require('ejs');
const marked = require('marked');
const plantuml = require('node-plantuml');

class DatabaseDocumentationGenerator {
  constructor(config) {
    this.config = {
      type: config.type || 'mysql', // mysql, postgresql, mssql, oracle
      host: config.host || 'localhost',
      port: config.port,
…

Example 2: Python Database Documentation Generator with SchemaSpy Integration

# database_doc_generator.py
import os
import json
import subprocess
import sqlite3
import psycopg2
import mysql.connector
import pymongo
from pathlib import Path
from typing import Dict, List, Any, Optional
from datetime import datetime
from jinja2 import Template
import graphviz
import yaml
from dataclasses import dataclass, asdict
import pandas as pd

@dataclass
…