---
name: database-schema-formatter
description: "Normalises raw table definitions, whether DDL dumps, ORM models, or notes, into one consistent Markdown schema reference with aligned tables, keys, and a version header, ready for a README or wiki. Use when raw DDL, ORM models, or hand-written table notes should be reformatted into a clean, consistent Markdown or HTML schema reference with a version header. Do not use for writing explanatory documentation with column meanings and join guidance, designing tables, or checking a schema for problems. Related topics: coding, database."
---

# Database Schema Formatter

Normalises raw table definitions, whether DDL dumps, ORM models, or notes, into one consistent Markdown schema reference with aligned tables, keys, and a version header, ready for a README or wiki.

## When to use

Use this skill when raw DDL, ORM models, or hand-written table notes should be reformatted into a clean, consistent Markdown or HTML schema reference with a version header. Do not use it for writing explanatory documentation with column meanings and join guidance, designing tables, or checking a schema for problems.

## 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. Parse the definitions from whatever form they take into a uniform set of tables, columns, types, keys, and defaults.
3. Render each table under a level-two heading with its primary key line and a Name, Type, Nullable, Default, Key, Notes table using the chosen alignment.
4. Normalise type spellings to one convention and sort tables alphabetically so versions diff cleanly.
5. Add the Relationships section with one child.column references parent.column line per foreign key when requested.
6. Prepend the version header and notes and return everything as one fenced block in the chosen style.

## Inputs

- **Table definitions** (longer free text)
- **Include foreign key relationships** (choose one: Yes, No)
- **Output style** (choose one: Markdown, HTML)
- **Column alignment in tables** (choose one: Left, Center, Right)
- **Additional notes** (longer free text)
- **Schema version** (free text, e.g. "v1.0")

## Output

A single fenced block (markdown or html) containing the version header, notes, one uniformly structured section per table in alphabetical order, and a Relationships section when requested.

## Prompt template

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

### Database Schema Formatter

Format these table definitions into a consistent Markdown schema reference.

- Table definitions: {{Table definitions}}
- Include foreign key relationships: {{Include foreign key relationships}}
- Output style: {{Output style}}
- Column alignment in tables: {{Column alignment in tables}}
- Additional notes: {{Additional notes}}
- Schema version: {{Schema version}}

Parse whatever form the definitions arrive in and bring every table to the same shape: a level-two heading with the table name, one line stating the primary key, then a table with the columns Name, Type, Nullable, Default, Key, Notes in that order, with the chosen alignment applied to every column. Normalise type spellings to one convention per document (varchar(255) in one place and character varying in another is the inconsistency this exists to remove) and sort tables alphabetically so the reference diffs cleanly between versions. When relationships are requested, add a Relationships section after the tables with one line per foreign key in the form child.column references parent.column. Put the schema version and the date at the top, the additional notes under it, and nothing else outside this structure. Return the whole reference as a single fenced block with the markdown language identifier (or html when that style is chosen) so it can be pasted without reformatting.

## Pitfalls

- Keeping each table's original column order and type spelling, so the reference inherits the inconsistency it was meant to remove.
- Adding commentary or explanations between tables, which belongs in documentation and breaks copy-paste into a wiki.
- Dropping defaults and nullability because the source omitted them; write unknown rather than guessing.
