Design a relational database schema
Designs a relational schema from requirements and access patterns, with keys, constraints, types, indexes and DDL. Use when starting a new service or feature that stores data.
A schema outlives the code around it. Mistakes such as a missing constraint, money stored as a float, a timestamp without a time zone or a tenant key left out of an index are cheap on day one and expensive after a year of data. The database should enforce the rules it can, so bad data cannot get in through any code path.
Design a schema for: Only if [ACCESS_PATTERNS] is given: Access patterns:
- List the entities, their relationships and cardinalities, and the business rules the data must obey. Write down every assumption you make.
- Model to third normal form first. Denormalise only where a listed access pattern needs it, and say which one.
- Choose keys: a surrogate primary key (identity integer, or a time-ordered UUID when ids are created outside the database or exposed publicly), plus natural unique keys as
UNIQUEconstraints. - Choose types deliberately: exact decimals for money (with the currency stored alongside), time-zone-aware timestamps, text with
CHECKconstraints or lookup tables for small fixed sets, and JSON only for data that is genuinely schemaless. - Enforce rules in the database:
NOT NULLby default, foreign keys with an explicitON DELETEbehaviour,UNIQUEandCHECKconstraints. - Derive indexes from the access patterns, one per pattern at most, with column order explained. Index foreign keys used in joins or cascading deletes.
- For multi-tenant data, put the tenant key in every tenant-owned table, in its unique constraints and first in its indexes.
- Model only what the requirements need. Add audit columns, soft deletes or history tables only when a requirement asks for them, and list them under Trade-offs as options otherwise.
- Use DDL that runs on as written. Do not mix dialects.
- Every index maps to a named access pattern or foreign key.
- When a requirement is ambiguous in a way that changes the model (one-to-many or many-to-many, hard or soft delete), pick one, say so in Assumptions, and add the question to Open questions.
- Separate what you verified from what you inferred. Mark inferences as such.
- When you do not know, say "I don't know" once and state what would settle it.
Assumptions
Numbered.
Diagram
A Mermaid erDiagram with every table, key and relationship.
DDL
One SQL code block that creates every table, constraint and index in dependency order.
Access patterns
| Pattern | Query shape | Index used |
Trade-offs
Each significant choice, the alternative, and why you chose this one.
Open questions
Questions whose answers would change the schema. "None" if none.
1 required value still a placeholder; the assistant will ask for it.
details
- kind
- Prompt: a task you run by name to get one finished thing back
- domain
- Software engineering
- category
- Data engineering
- level
- Intermediate
- made for
- Backend engineer, Data engineer, Software architect, Software engineer
- risk
- read-only
- version
- v1.0.0 · experimental
- reviewed
- 2026-10-02
- works in
- Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Antigravity, OpenCode, Windsurf, Zed, Continue, AGENTS.md, ChatGPT, claude.ai
use in
npx @hermes-hq/hodios install design-database-schema --target claude-codenpx skills add hermes-hq/hodios-dist --skill design-database-schema -a claude-codeclaude plugin marketplace add hermes-hq/hodios-distclaude plugin install hodios-software-engineering@hodiosThe plugin brings every entry in this domain at once.
pairs well with
All of Data engineeringPlan a zero-downtime schema change
Turns current table DDL and a desired change into expand and contract steps with lock-safe SQL, app changes, backfill, verification and rollback. Use before altering a live table.
plan-zero-downtime-schema-changeOptimise a slow SQL query
Speeds up a slow SQL query from its execution plan, proposing rewrites and indexes with expected gains and their write-cost trade-offs. Use when one query dominates latency or database load.
optimize-sql-queryData engineer
Acts as a data engineer who designs for idempotency, backfills and observability, treats schemas as contracts with their consumers, and asks who depends on each table before changing it.
data-engineerDesign a data pipeline
Designs a batch or streaming data pipeline sized to stated volumes, covering sources, schedule, idempotency, late data, backfills and monitoring. Use before building or replacing a pipeline.
design-data-pipelineDesign a star schema
Designs a dimensional model from the questions analysts need answered: business processes, grain, facts, dimensions, slowly changing dimension types and DDL. Use when building a warehouse layer.
design-star-schemaGenerate realistic seed data
Generates realistic, referentially consistent fixture data for a database schema, with labelled edge cases and no real personal data. Use for local development, demos and integration tests.
generate-realistic-seed-data