Database Patterns

What it does

When your agent uses it

• Creating migrations
• Designing schemas
• Normalizing data
• Managing database versions

Example prompts

• “/database-patterns”

Requirements

• Python 3
• Compatibility (from SKILL.md): Claude Code 2.1.277+.
• Pre-approved tools (allowed-tools): Read, Glob, Grep, WebFetch, WebSearch

What it can do on your machine

Read from SKILL.md and the folder at commit 0ef71d2. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Glob
  • Grep
  • WebFetch
  • WebSearch

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/, which the agent can run.

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • postgresql.org
  • alembic.sqlalchemy.org
  • github.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Claude Code 2.1.277+.

  From compatibility in the SKILL.md frontmatter.

Context cost

Database Patterns loads about 2.5k tokens when it runs, and up to ~7.6k if it reads all its reference files. Until then it costs about 63 tokens; SKILL.md has 665 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~63

When it runs · the whole SKILL.md, loaded when a task matches

~2.5k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~7.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from yonatangross/orchestkit at commit 0ef71d2, republished under its MIT licence (© yonatangross). 665 words, ~2,531 tokens.

name

database-patterns

description

Database design and migration patterns for Alembic migrations, schema design (SQL/NoSQL), and database versioning. Use when creating migrations, designing schemas, normalizing data, managing database versions, or handling schema drift.

allowed-tools

Read, Glob, Grep, WebFetch, WebSearch

compatibility

Claude Code 2.1.277+.

license

MIT

user-invocable

false

disable-model-invocation

false

metadata.owner-agent

database-engineer

metadata.category

document-asset-creation

metadata.version

2.0.0

metadata.author

OrchestKit

metadata.complexity

medium

metadata.tags

database, migrations, alembic, schema-design, versioning, postgresql, sql, nosql

paths

**/migrations/**, **/models/**, alembic.ini, **/schema*

<!-- directive-density: intentional (teaches migration anti-patterns; NEVER markers describe real production-break conditions, not aspirational guidance) -->

# Alembic: Auto-generate migration from model changes
# alembic revision --autogenerate -m "add user preferences"

def upgrade() -> None:
    op.add_column('users', sa.Column('org_id', UUID(as_uuid=True), nullable=True))
    op.execute("UPDATE users SET org_id = 'default-org-uuid' WHERE org_id IS NULL")

def downgrade() -> None:
    op.drop_column('users', 'org_id')

-- Schema: Normalization to 3NF with proper indexing
-- PG18: prefer uuidv7() (time-ordered, better B-tree locality) over gen_random_uuid() (random v4)
CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT uuidv7(),
    customer_id UUID NOT NULL REFERENCES customers(id),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);
CREATE INDEX idx_orders_customer_id ON orders(customer_id);

# NEVER: Add NOT NULL without default or two-phase approach
op.add_column('users', sa.Column('org_id', UUID, nullable=False))  # LOCKS TABLE!

# NEVER: Use blocking index creation on large tables
op.create_index('idx_large', 'big_table', ['col'])  # Use CONCURRENTLY

# NEVER: Skip downgrade implementation
def downgrade():
    pass  # WRONG - implement proper rollback

# NEVER: Modify migration after deployment - create new migration instead

# NEVER: Run migrations automatically in production
# Use: alembic upgrade head --sql > review.sql

# NEVER: Run CONCURRENTLY inside transaction
op.execute("BEGIN; CREATE INDEX CONCURRENTLY ...; COMMIT;")  # FAILS

# NEVER: Delete migration history
command.stamp(alembic_config, "head")  # Loses history

# NEVER: Skip environments (Always: local -> CI -> staging -> production)

© yonatangross, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 24 other files (scripts, references) in src/skills/database-patterns of yonatangross/orchestkit.

• SKILL.md
• metadata.json
• references/cost-comparison.md
• references/db-migration-paths.md
• references/migration-testing.md
• references/ork-delta.md
• references/postgres-vs-mongodb.md
• references/storage-and-cms.md
• rules/_sections.md
• rules/_template.md
• rules/alembic-branching.md
• rules/alembic-data-migration.md
• rules/db-selection.md
• rules/migration-rollback.md
• rules/migration-zero-downtime.md
• rules/schema-indexing.md
• rules/schema-normalization.md
• rules/schema-nosql.md
• rules/versioning-changelog.md
• … and 6 more

Open the folder on GitHubat commit 0ef71d2