# Database Design Doc > Generate a professional Database Design document as a formatted Word (.docx) file — database overview, ER diagram placeholder, table/collection definitions, relationships, indexing, migrations, retention, and PII handling. Use this whenever someone asks for a "database design doc," "schema documentation," "data model doc," or wants a standalone document describing how a system's data is structured and managed (as distinct from the system's overall architecture or API contract, which have their own companion skills). Part of an enterprise handover documentation suite (see also: project-overview-doc, architecture-document, high-level-design, operations-deployment-guide, support-runbook, api-documentation, release-maintenance-guide) but fully usable standalone. - Skill: `vedkathe/database-design-doc` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add vedkathe/database-design-doc` - Raw SKILL.md: https://api.skillmd.com/api/skills/vedkathe/database-design-doc/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: VedKathe (https://skillmd.com/u/vedkathe) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/vedkathe/database-design-doc --- # Database Design Document Generator Produce a single `.docx` document describing how a system's data is structured, related, and managed — detailed enough that another engineer could write correct queries and migrations against it without asking the original team. Backup/restore *procedures* belong in the companion `operations-deployment-guide` skill — cross-reference it rather than duplicating; this document covers the schema and data model itself. ## Sections (in this order) Cover page, Version History, Document Approval, Revision Log, and TOC are automatic — your `sections` array starts at "1. Database Overview". | # | Section | Content | Diagram? | |---|---|---|---| | 1 | Database Overview | Engine(s), version, hosting/managed service | | | 2 | Entity-Relationship Overview | Narrative walkthrough of the major entities and how they relate | **ER Diagram** | | 3 | Table / Collection Definitions | Table: Table/Collection, Key Columns, Purpose, Notes (indexes, constraints) | | | 4 | Relationships & Constraints | Foreign keys, cardinality, cascade behavior | | | 5 | Indexing Strategy | What's indexed and why, any composite/partial indexes | | | 6 | Data Types & Conventions | Naming conventions, standard types (timestamps, IDs, enums) | | | 7 | Migrations Strategy | Tool used (e.g., Flyway, Prisma Migrate, Alembic), how migrations are versioned and applied | | | 8 | Data Retention & Archival | Retention periods per table where relevant, archival approach | | | 9 | PII & Sensitive Data Handling | Which fields are PII/sensitive, how they're protected (encryption, masking, access control) | | | 10 | Performance Considerations | Query optimization notes, partitioning/sharding if applicable | | | 11 | Appendix | Link to Operations & Deployment Guide for backup/restore procedures; schema migration repo link | | ## Diagram Policy **Applies to the `.docx` path only** — Markdown embeds Mermaid source directly instead of rendering anything (see "Output Format" below). Prefer a real Mermaid diagram — rendered via `mmdc` and embedded with `B.diagramImage()` — over `diagramPlaceholder()`, but only once you have concrete structure to draw (real names, not "TBD"). Read `references/diagram-generation.md` when you're actually about to render one — it has the full build order, the bundled config (`assets/mermaid-config.json`), the exact `mmdc` flags, and token-saving tips. Skip it entirely if this document ends up needing no diagrams. ## Missing Information Policy Never invent table names, columns, or relationships you have no basis for — a fabricated schema detail is actively harmful here, since someone may write a query or migration against it. Use `toBeCompleted("...")` for sections you lack real input for, explaining what's needed (e.g., "point me at the schema file or run `\d` against the database"), and still generate everything else. ## Output Format Ask the user which output format they want, unless they've already said so in this request (e.g., "as a docx", "in markdown," "just give me an .md file") — a quick single-choice question is enough, don't block on it otherwise: - **Word document (.docx)** — the default assumption if the person hasn't specified and their context suggests a formal deliverable. Follow "Using the builder" below. - **Markdown (.md)** — no script needed, write the file directly. Use these conventions so it stays structurally equivalent to the docx version: - Front matter: instead of a cover page, open with the title as an `#` heading, the project name as an italic subtitle line, then a metadata table instead of separate Version History / Approval / Revision Log tables: ```markdown # Database Design *Acme Order Platform* | Field | Value | |---|---| | Version | 0.1 | | Author | Jane Doe | | Date | 2026-07-19 | | Status | Draft | | Approved By | Jane Doe (Tech Lead) | ``` - Headings: `#`/`##`/`###`/`####` matching the same section levels used in the table above — don't flatten everything to one level, that's what keeps the document skimmable and consistent with the docx version. - Tables: standard Markdown tables. - Diagrams — unlike the `.docx` path, don't render or embed an image here. Write the actual Mermaid source directly in a fenced code block; GitHub, GitLab, Obsidian, and most modern Markdown viewers render `mermaid` code blocks natively, so this is a real diagram, not a placeholder: ````markdown ```mermaid flowchart TD A[Client] --> B[API Gateway] B --> C[Order Service] C --> D[(Database)] ``` ```` Only fall back to a text placeholder if you don't yet have concrete enough detail to draw something real (mirrors `toBeCompleted` above): ```markdown > 📊 **DIAGRAM PLACEHOLDER — TO BE COMPLETED** > Not enough detail yet to draw the System Architecture Diagram — need > the actual component names and how they connect. ``` - "To be completed" callout — same blockquote treatment: ```markdown > ⚠️ **TO BE COMPLETED** > Explanation of what input is needed to fill this in. ``` - Save as `Database_Design.md` instead of `Database_Design.docx`. ## Workflow Ask the output format first (see "Output Format" above). For Markdown, skip straight to writing the file using those conventions — the numbered steps below describe the `.docx` path. 1. Gather what's available — ideally direct access to the schema (migration files, an ORM's model definitions, or a live `\d`/`DESCRIBE` dump); otherwise ask for the table list and key relationships. 2. Draft each section as data using the builder functions below. 3. Build with `scripts/docx_builder.js`. 4. Skip PDF conversion by default — `docx_builder.js` is already tested and hardened (table widths and text alignment are enforced at the library level), so routine generations don't need a re-render just to confirm it worked. Only convert to PDF and view it if the user explicitly asks for visual verification, or if something about this generation is unusual (e.g., a new kind of content the library hasn't handled before, or a reported rendering problem). When you do need it: `soffice --headless --convert-to pdf .docx` (or `libreoffice --headless ...`), then `pdftoppm -jpeg -r 100 .pdf page` and view the images. 5. Save to `/mnt/user-data/outputs/Database_Design.docx` (or `.md` if that's the chosen format) and present it. ## Using the builder (for the .docx path) This library requires the `docx` npm package. Before running any script, check it's available with `node -e "require('docx')"`; if that fails, install it with `npm install docx` in the working directory first — don't assume it's pre-installed, since that varies by environment. ```javascript const B = require("./scripts/docx_builder.js"); const sections = [ B.h1("1. Database Overview"), B.para("PostgreSQL 16, hosted on AWS RDS with a read replica in the same region."), B.h1("3. Table / Collection Definitions"), B.table(["Table", "Key Columns", "Purpose", "Notes"], [["orders", "id, customer_id, status, created_at", "One row per customer order", "Indexed on customer_id, status"]], [2000, 2400, 3200, 2200]), // Prefer B.diagramImage(path, {caption}) with a real mmdc render when // possible (see "Diagram Policy" above) — diagramPlaceholder() is the fallback: B.diagramPlaceholder({ name: "Entity-Relationship Diagram", purpose: "Show all tables and their relationships.", recommendedContent: ["orders", "order_items", "customers", "inventory", "warehouses"], }), B.h1("9. PII & Sensitive Data Handling"), B.toBeCompleted("PII field inventory wasn't provided — ask which columns contain personal data and how they're currently protected."), ]; await B.buildDocument("/mnt/user-data/outputs/Database_Design.docx", { docLabel: "Database Design", title: "Database Design", subtitle: "Acme Order Platform", versionHistory: [["0.1", "2026-07-19", "Jane Doe", "Initial draft"]], approvers: [["Jane Doe", "Tech Lead", "", ""]], revisionLog: [], sections, }); ``` Available functions: `h1`/`h2`/`h3`/`h4`, `para`, `bullets`, `table(headers, rows, widths)`, `pageBreak`, `toBeCompleted(explanation)`, `diagramPlaceholder({name, purpose, recommendedContent, notes})`, and `buildDocument(path, options)`. Always use heading functions for titles so Word's Table of Contents and Navigation Pane work correctly. ## Success Criteria An engineer new to the project should be able to write a correct query, migration, or data-access-layer change using only this document — accurate table structure, relationships, and any PII handling rules that affect how they're allowed to touch the data.