К основному содержанию
скилл CX Codex

database-patterns · yonatangross — скилл для Claude Code: схема и установка

Скилл database-patterns помогает проектировать схемы, создавать миграции Alembic и находить расхождения между версиями базы. Включается при работе с SQL и NoSQL.

MIT 238 установок ★ 305 обновлён 2026-11-07

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add yonatangross/orchestkit --skill database-patterns -a claude-code
Открыть на GitHub

Что делает database-patterns

Скилл разбирает проектирование и нормализацию схем, миграции Alembic и версионирование базы. Он помогает выполнять пакетные обновления данных, добавлять ограничения, выбирать индексы и разрешать конфликты веток миграций.

Внутри есть правила для SQL и NoSQL: нормализация 1NF–3NF, B-tree, GIN и HNSW, частичные и покрывающие индексы, встраивание документов и ссылки. Отдельные правила посвящены журналу изменений, обнаружению schema drift, миграциям без простоя и выбору PostgreSQL или MongoDB.

Скилл работает с Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode. Он использует Alembic и PostgreSQL, но не заменяет их документацию; для async-приложений в тексте указан SQLAlchemy 2.0.

Какие задачи решает

  • спроектировать нормализованную схему SQL или NoSQL
  • создать пакетную миграцию Alembic
  • разрешить конфликт веток миграций
  • найти расхождения схем между окружениями
  • подобрать индексы для PostgreSQL

Примеры запросов агенту

  • Спроектируй нормализованную схему для таблиц заказов и клиентов.
  • Создай миграцию Alembic для добавления обязательного поля без простоя.
  • Проверь проект на расхождение схем между окружениями и предложи исправление.

Как установить database-patterns

1Через Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill database-patterns -a claude-code

2Вручную: положить файлы

~/.claude/skills/database-patterns/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/database-patterns/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о database-patterns

Как установить database-patterns в Claude Code?

Выполните npx skills add yonatangross/orchestkit --skill database-patterns -a claude-code, затем проверьте файл ~/.claude/skills/database-patterns/SKILL.md.

Что делает database-patterns?

Скилл помогает проектировать схемы, писать и версионировать миграции Alembic, обнаруживать schema drift и выбирать подходы для SQL и NoSQL.

Какие технологии покрывает database-patterns?

Правила охватывают Alembic, PostgreSQL, SQLAlchemy 2.0 async-приложения, SQL и NoSQL-схемы. Для выбора базы отдельно рассматриваются PostgreSQL и MongoDB.

Исходный текст

SKILL.md · MIT
---
name: database-patterns
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Schema design, Alembic migrations and database versioning. Use when creating migrations, designing or normalizing schemas, or fixing schema drift."
user-invocable: false
disable-model-invocation: false
targets:
  - library: sqlalchemy
    version: ">=2.1.1"
metadata:
  owner-agent: "database-engineer"
  category: document-asset-creation
  version: "2.0.0"
  author: "OrchestKit"
  complexity: "medium"
  tags: "database, migrations, alembic, schema-design, versioning, postgresql, sql, nosql"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
paths: ["**/migrations/**", "**/models/**", "alembic.ini", "**/schema*"]
path_patterns: ["*.sql", "**/migrations/**", "**/alembic/**", "**/prisma/**"]
---

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

# Database Patterns

Comprehensive patterns for database migrations, schema design, and version management. Each category has individual rule files in `rules/` loaded on-demand.

## Quick Reference

| Category | Rules | Impact | When to Use |
|----------|-------|--------|-------------|
| [Alembic Migrations](#alembic-migrations) | 2 | CRITICAL | Data migrations, branch management |
| [Schema Design](#schema-design) | 3 | HIGH | Normalization, indexing strategies, NoSQL patterns |
| [Versioning](#versioning) | 2 | HIGH | Changelogs, schema drift detection |
| [Zero-Downtime Migration](#zero-downtime-migration) | 2 | CRITICAL | Expand-contract, pgroll, rollback monitoring |

| [Database Selection](#database-selection) | 1 | HIGH | Choosing the right database, PostgreSQL vs MongoDB, cost analysis |

**Total: 10 rules across 5 categories**

This skill is a wrap around Alembic and PostgreSQL, not a replacement for their
docs. Read `references/ork-delta.md` first: it holds the
version floors, corrections and house conventions that upstream does not carry.
Everything in the table below was removed on purpose.

## Upstream coverage (do not restate)

These topics are vendor documentation. Fetch them from the source instead of
re-teaching them here.

| Topic | First-party source |
|-------|--------------------|
| Alembic autogenerate, async `env.py` template, `revision`/`upgrade`/`downgrade`/`history` CLI | https://alembic.sqlalchemy.org/en/latest/autogenerate.html (our one correction to the async template is in `references/ork-delta.md`) |
| Migration branches, merge revisions, tuple `down_revision`, branch labels | https://alembic.sqlalchemy.org/en/latest/branches.html |
| Multi-database `env.py`, batched backfill recipes, migration hooks, environment-conditional migrations | https://alembic.sqlalchemy.org/en/latest/cookbook.html |
| Rollback and data-integrity test harnesses | `references/migration-testing.md` |
| JSONB operators, indexing and storage tradeoffs | https://www.postgresql.org/docs/current/datatype-json.html (normal forms and the house denormalization call stay in `rules/schema-normalization.md`) |
| Full index-type reference and syntax (B-tree, GIN, partial, covering, `CREATE INDEX CONCURRENTLY`, `REINDEX`) | https://www.postgresql.org/docs/current/sql-createindex.html (the house subset we actually apply stays in `rules/schema-indexing.md`) |
| `lock_timeout`, `statement_timeout`, advisory locks during migration | https://www.postgresql.org/docs/current/runtime-config-client.html and `rules/versioning-drift.md` |
| Enum type changes | https://www.postgresql.org/docs/current/datatype-enum.html |
| Table partitioning | https://www.postgresql.org/docs/current/ddl-partitioning.html |
| Trigger functions | https://www.postgresql.org/docs/current/plpgsql-trigger.html |
| Foreign-key cascade semantics | https://www.postgresql.org/docs/current/ddl-constraints.html |
| Temporal and audit-trail tables, CDC change logs, stored-procedure and view versioning | https://www.postgresql.org/docs/18/sql-createtable.html (read `references/ork-delta.md` before assuming these give row history) |
| HNSW and vector index tuning (`m`, `ef_construction`, `hnsw.ef_search`) | https://github.com/pgvector/pgvector |
| Generic pre-deployment, backup and schema-review checklists | https://alembic.sqlalchemy.org/en/latest/tutorial.html |
| Async SQLAlchemy sessions, FastAPI wiring, connection pool tuning | `ork:python-backend` skill |

## Quick Start

```python
# 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')
```

```sql
-- 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);
```

## Alembic Migrations

Migration management with Alembic for SQLAlchemy 2.0 async applications.

| Rule | File | Key Pattern |
|------|------|-------------|
| Data Migration | `rules/alembic-data-migration.md` | Batch backfill, two-phase NOT NULL, zero-downtime |
| Branching | `rules/alembic-branching.md` | Feature branches, merge migrations, conflict resolution |

Autogenerate setup is upstream. Our one deviation from Alembic's async `env.py`
template (the `in_greenlet()` guard) is in `references/ork-delta.md`.

## Schema Design

SQL and NoSQL schema design with normalization, indexing, and constraint patterns.

| Rule | File | Key Pattern |
|------|------|-------------|
| Normalization | `rules/schema-normalization.md` | 1NF-3NF, when to denormalize, JSON vs normalized |
| Indexing | `rules/schema-indexing.md` | B-tree, GIN, HNSW, partial/covering indexes |
| NoSQL Patterns | `rules/schema-nosql.md` | Embed vs reference, document design, sharding |

## Versioning

Database version control and change management across environments.

| Rule | File | Key Pattern |
|------|------|-------------|
| Changelog | `rules/versioning-changelog.md` | Schema version table, semantic versioning, audit trails |
| Drift Detection | `rules/versioning-drift.md` | Environment sync, checksum verification, migration locks |

Rollback testing lives in `references/migration-testing.md`;
the docstring convention for lossy downgrades is in
`references/ork-delta.md`.

## Database Selection

Decision frameworks for choosing the right database. Default: PostgreSQL.

| Rule | File | Key Pattern |
|------|------|-------------|
| Selection Guide | `rules/db-selection.md` | PostgreSQL-first, tier-based matrix, anti-patterns |

## Key Decisions

| Decision | Recommendation | Rationale |
|----------|----------------|-----------|
| Async dialect | `postgresql+asyncpg` | Native async support for SQLAlchemy 2.0 |
| NOT NULL column | Two-phase: nullable first, then alter | Avoids locking, backward compatible |
| Large table index | `CREATE INDEX CONCURRENTLY` | Zero-downtime, no table locks |
| Normalization target | 3NF for OLTP | Reduces redundancy while maintaining query performance |
| Primary key strategy | UUID for distributed, INT for single-DB | Context-appropriate key generation |
| Soft deletes | `deleted_at` timestamp column | Preserves audit trail, enables recovery |
| Migration granularity | One logical change per file | Easier rollback and debugging |
| Production deployment | Generate SQL, review, then apply | Never auto-run in production |

## Anti-Patterns (FORBIDDEN)

```python
# 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)
```

## Detailed Documentation

| Resource | Description |
|----------|-------------|
| `references/ork-delta.md` | Our corrections and house conventions. Read this first |
| `references/migration-testing.md` | Upgrade/downgrade cycle and data-integrity test harnesses |
| `references/postgres-vs-mongodb.md` | Head-to-head comparison behind the PostgreSQL-first default |
| `references/db-migration-paths.md` | Cross-engine migration risk matrix |
| `references/cost-comparison.md` | Managed database cost analysis |
| `references/storage-and-cms.md` | Object storage and CMS selection |
| `scripts/` | Migration template, model change detector |

## Zero-Downtime Migration

Safe database schema changes without downtime using expand-contract pattern and online schema changes.

| Rule | File | Key Pattern |
|------|------|-------------|
| Expand-Contract | `rules/migration-zero-downtime.md` | Expand phase, backfill, contract phase, pgroll automation |
| Rollback & Monitoring | `rules/migration-rollback.md` | pgroll rollback, lock monitoring, replication lag, backfill progress |

## Related Skills

- `sqlalchemy-2-async` - Async SQLAlchemy session patterns
- `ork:testing-integration` - Integration testing patterns including migration testing
- `caching` - Cache layer design to complement database performance
- `ork:performance` - Performance optimization patterns

© OrchestKit · MIT · yonatangross/orchestkit

Похожие скиллы

Все скиллы по теме «Данные и базы» →

Сначала — database-patterns от других авторов.

database-patterns majiayu000 Скилл database-patterns задаёт правила связки PostgreSQL и Redis: выбор типов, индексы, работу с JSONB, стратегии кэширования и защиту от cache stampede. CX Codex +1 162установок database-patterns c0x12c Скилл database-patterns для Claude Code и Codex, задаёт правила проектирования БД: типы колонок, UUID-ключи, мягкое удаление и шаблоны миграций. Агент использует их при создании таблиц и репозиториев. CX Codex +1 ★ 111звёзд репо database-management-patterns manutej Скилл database-management-patterns для Claude Code — справочник по PostgreSQL и MongoDB для проектирования схем, работы с индексами, транзакциями, репликацией и шардированием. CX Codex +1 467установок database-architect davila7 Скилл database-architect превращает Claude Code в архитектора баз данных. Он помогает выбрать СУБД, спроектировать схему, спланировать партиционирование и безопасную миграцию данных под нагрузку. CX Codex +1 586установок database-cloud-optimization-database-architect Seth Hobson Субагент database-cloud-optimization-database-architect проектирует архитектуру баз данных с нуля и перерабатывает существующие схемы. Помогает выбрать СУБД, настроить шардирование, кеширование и индексы. CX Codex ★ 42 780звёзд репо database-design alirezarezvani Промпт database-design для Claude Code содержит шаблоны для реляционных схем, NoSQL и хранилищ данных; по ним модель выдаёт ERD, DDL, индексы и план масштабирования. GP ChatGPT ★ 788звёзд репо database-design-patterns curiositech Скилл database-design-patterns проектирует схемы реляционных БД: нормализует таблицы до 3NF, подбирает типы индексов и планирует миграции без простоя сервиса. CX Codex +1 152установок design-database-schema davila7 Команда design-database-schema проектирует структуру базы данных с учётом связей, ограничений и запросов. Она пригодится при создании схемы или пересмотре существующей. CX Codex +1 1 021установок

Из того же набора86

Весь набор →
python-backend Скилл python-backend для Claude Code и Codex подтягивает правила асинхронного бэкенда на Python при работе с файлами *.py и манифестами зависимостей. Настраивает связку FastAPI, SQLAlchemy 2.0 и asyncio. CX Codex +1 250установок accessibility Скилл accessibility для Claude Code помогает добавлять доступность в веб-интерфейсы. Активируется при работе с клавиатурной навигацией, экранными дикторами и ARIA-компонентами. CX Codex +1 246установок memory-fabric Скилл memory-fabric для Claude Code управляет поиском по графу знаний, парсит запросы, объединяет дубликаты и ранжирует факты. Включается при отладке внутренней логики памяти агента. CX Codex +1 244установок multimodal-llm Скилл multimodal-llm для Claude Code и Codex подбирает архитектурные паттерны для работы со зрением, речью и генерацией видео. Агент подключает его при распознавании изображений, транскрипции аудио и вызовах видео-API. CX Codex +1 243установок architecture-patterns Скилл architecture-patterns проверяет соблюдение чистой архитектуры, деление бэкенда на слои и глубину вложенности папок. Включается при проектировании границ сервисов и рефакторинге. CX Codex +1 236установок performance Скилл performance помогает находить узкие места во фронтенде, бэкенде и LLM-инференсе: от медленных React-рендеров до задержек API. CX Codex +1 233установок github-operations Скилл github-operations управляет issues, pull requests, milestones и Projects v2 через gh CLI, REST и GraphQL. Включается при работе с ресурсами GitHub. CX Codex +1 230установок remember Скилл remember для Claude Code передаёт решение или шаблон в объединённый скилл memory для сохранения в графе знаний. Запускается командой /ork:remember. CX Codex +1 229установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой