---
name: database-schema-documenter
description: "Produces a data dictionary for an existing database that analysts and new engineers can read: purpose per table, every column with type and meaning, keys and relationships, and the indexes that matter for queries. Use when an existing database needs a data dictionary with table purposes, column meanings, keys, relationships, and indexes for engineers or analysts. Do not use for designing a new schema, generating DDL, reformatting raw definitions into tables, or validating a schema against best practice. Related topics: coding, database."
---

# Database Schema Documenter

Produces a data dictionary for an existing database that analysts and new engineers can read: purpose per table, every column with type and meaning, keys and relationships, and the indexes that matter for queries.

## When to use

Use this skill when an existing database needs a data dictionary with table purposes, column meanings, keys, relationships, and indexes for engineers or analysts. Do not use it for designing a new schema, generating DDL, reformatting raw definitions into tables, or validating a schema against best practice.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Group tables by domain in an overview and describe how a typical record flows through them.
3. Write each table's purpose and a columns table with type, nullability, default, and meaning, marking inferred meanings.
4. List primary keys, foreign keys with relationship direction when requested, and indexes with the query pattern each serves when requested.
5. Add the audience section: Common joins for analysts, Constraints and invariants for engineers, or both.
6. Insert the diagram placeholder when a style is chosen and assemble the document with a title, contents, and consistent headings in the selected format.

## Inputs

- **Database platform** (choose one: MySQL, PostgreSQL, Oracle, SQL Server, SQLite, MariaDB)
- **Tables definition** (longer free text)
- **Include indexes** (choose one: Yes, No)
- **Include foreign key relationships** (choose one: Yes, No)
- **Output format** (choose one: Markdown, HTML, PDF outline)
- **Diagram style** (choose one: ERD, UML, None)
- **Primary audience** (choose one: Backend engineers, Data analysts, Both)

## Output

One document in the selected format: title, table of contents, overview by domain, a section per table (purpose, columns table, keys, relationships, indexes), the audience section, and a diagram placeholder when requested.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### Database Schema Documenter

Write the schema documentation for this database.

- Database platform: {{Database platform}}
- Tables definition: {{Tables definition}}
- Include indexes: {{Include indexes}}
- Include foreign key relationships: {{Include foreign key relationships}}
- Output format: {{Output format}}
- Diagram style: {{Diagram style}}
- Primary audience: {{Primary audience}}

Start with an overview that groups the tables by domain (users and auth, orders, catalogue) and explains in a paragraph how a typical record flows through them. For each table write a purpose sentence, a columns table with name, type, nullability, default, and a plain-language meaning (infer meanings from names and comments and mark inferred ones), then the primary key and, when requested, the foreign keys with the direction of the relationship. When indexes are requested, list them with the query pattern each one serves, since that is what an analyst needs to write fast queries. For analysts, add a "Common joins" section with the join keys between related tables; for engineers, add a "Constraints and invariants" section. When a diagram style is chosen, insert a placeholder block describing the entities and edges the diagram must show. Produce one document in the selected format with a title, a table of contents, and consistent heading levels.

## Pitfalls

- Listing columns without meanings, which turns the document into a copy of the DDL nobody reads.
- Describing indexes without the query they serve, so analysts still guess which filters are fast.
- Omitting the overview, so a reader has to reverse-engineer the domain from table names.
