db-design

Reviews database table designs and guides status column modeling with a five-step framework.

Updated Jan 30, 2026
One-click install
npx skills add https://github.com/RyoMa99/chezmoi_dotfiles --skill db-design-ryoma99
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: db-design
Source: https://github.com/RyoMa99/chezmoi_dotfiles/tree/main/dot_claude/skills/db-design
Command: npx skills add https://github.com/RyoMa99/chezmoi_dotfiles --skill db-design-ryoma99

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Database tables often accumulate anti-patterns like proliferating status columns, Boolean flag explosions, and NULL-based implicit states that lead to invalid data and unmaintainable schemas. This Skill provides a structured review framework and checklist to catch these issues before they reach production. ## Core Features & Use Cases - Five-Step Status Design Framework: Enumerate events, separate resources from events, define state transition diagrams, isolate external codes, and manage external classification values with their meanings. - Anti-Pattern Detection: Identifies Boolean flag proliferation, multiple status columns in one table, and NULL-based status representation, then proposes concrete alternative DDL. - Review Checklist: Provides an eight-point checklist for auditing existing schemas and new migration proposals. - Use Case: When asked to add payment_status and shipping_status columns to an orders table, the Skill flags the status-column sprawl anti-pattern and proposes separating payment and shipping lifecycles into dedicated event tables with explicit transition constraints. ## Quick Start Ask the AI to review your table design or migration for status management issues, for example by requesting a design review of an orders table that tracks payment and shipping states.

Frequently Asked Questions about db-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design a status column for a database table?

Start by enumerating the events that occur in your system, then define a state transition diagram before writing any DDL. Use a single VARCHAR status column with a CHECK constraint listing allowed values, and validate permitted transitions in the application layer.

How to handle multiple statuses like payment and shipping in one orders table?

Multiple status columns in one table signal the table has too many responsibilities. Separate each lifecycle into its own table or record state changes in an INSERT-only events table, keeping only the overall current state on the resource table.

Should I use Boolean flags or a status column in my schema?

Use a single status column when the flags represent mutually exclusive states, since three or more Booleans create invalid combinations. Boolean flags are acceptable only when they represent genuinely independent attributes, not lifecycle states.

Should I store external API status codes directly in my database?

No, store an internally defined status on your main table and keep external provider codes in a separate responses table with the raw payload. This protects internal logic from external API changes and prevents mixed status vocabularies.

When should I not use this status design framework?

The framework focuses specifically on status and state-transition modeling, not full schema design. Normalization, detail tables, index strategy, and relationship design for the rest of the schema still require standard database design judgment.