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

database-patterns · majiayu000 — скилл для Claude Code: что делает и как установить

Скилл database-patterns задаёт правила связки PostgreSQL и Redis: выбор типов, индексы, работу с JSONB, стратегии кэширования и защиту от cache stampede.

MIT 162 установок ★ 300 обновлён 2026-10-23

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

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

Скилл фиксирует архитектурный шаблон: PostgreSQL остаётся основным хранилищем транзакций и реляционных связей, а Redis отвечает за сессии, счётчики и кэш. В схемах баз данных он предлагает использовать UUID или BIGSERIAL вместо обычного INT, точные типы вроде NUMERIC(19,4) для денег и TIMESTAMPTZ для времени.

Внутрь заложены паттерны индексации: B-Tree по умолчанию, составные индексы с учётом префикса, частичные индексы и GIN для полей JSONB. Для работы с Redis расписаны структуры данных под конкретные задачи, шаблоны именования ключей через двоеточие и типовые интервалы TTL от 30 секунд для блокировок до суток для сессий.

Главный принцип миграций здесь категоричен: старые схемы не консервируют, данные сразу переводят в новую структуру без обратной совместимости.

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

  • спроектировать схему PostgreSQL с проверками и триггерами updated_at
  • выбрать структуру Redis и TTL под сессии или кэш объектов
  • настроить частичные или GIN-индексы для запросов по JSONB
  • реализовать паттерн cache-aside с защитой от stampede через блокировку

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

  • Напиши схему таблицы пользователей в PostgreSQL с полями статуса, метаданных в JSONB и триггером обновления даты
  • Покажи функцию на TypeScript для кэширования профиля через Redis по схеме cache-aside с TTL 15 минут
  • Составь составной и частичный индекс для таблицы заказов, чтобы ускорить выборку активных пользователей

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

1Через Skills CLI (Vercel)

npx skills add majiayu000/spellbook --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 majiayu000/spellbook --skill database-patterns -a claude-code. Файл скилла будет сохранён по пути ~/.claude/skills/database-patterns/SKILL.md.

Что делает этот скилл?

Он инструктирует агента применять готовые шаблоны для связки PostgreSQL и Redis, включая подбор типов данных, настройку индексов и паттерны работы с кэшем.

Когда скилл рекомендует использовать JSONB в PostgreSQL?

JSONB предлагается использовать экономно — только для полуструктурированных или динамических атрибутов, которые редко участвуют в фильтрации, тогда как частые поля выносятся в отдельные колонки.

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

SKILL.md · MIT
---
name: database-patterns
description: Use when designing PostgreSQL + Redis data models, indexes, caching strategies, JSONB usage, tiered storage, or cache consistency contracts.
---
# Database Patterns

## Core Principles

- **PostgreSQL Primary** — Relational data, transactions, complex queries
- **Redis Secondary** — Caching, sessions, real-time data
- **Index-First Design** — Design queries before indexes
- **JSONB Sparingly** — Structured data prefers columns
- **Cache-Aside Default** — Read-through, write-around
- **Tiered Storage** — Hot/Warm/Cold data separation
- **No backwards compatibility** — Migrate data, don't keep legacy schemas

---

## PostgreSQL

### Data Type Selection

| Use Case | Type | Avoid |
|----------|------|-------|
| Primary Key | `UUID` / `BIGSERIAL` | `INT` (range limits) |
| Timestamps | `TIMESTAMPTZ` | `TIMESTAMP` (no timezone) |
| Money | `NUMERIC(19,4)` | `FLOAT` (precision loss) |
| Status | `TEXT` + CHECK | `INT` (unreadable) |
| Semi-structured | `JSONB` | `JSON` (no indexing) |
| Full-text | `TSVECTOR` | `LIKE '%..%'` |

### Schema Design

```sql
-- Use UUID for distributed-friendly IDs
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE users (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  email TEXT UNIQUE NOT NULL,
  name TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'active'
    CHECK (status IN ('active', 'inactive', 'suspended')),
  metadata JSONB DEFAULT '{}',
  created_at TIMESTAMPTZ DEFAULT NOW(),
  updated_at TIMESTAMPTZ DEFAULT NOW()
);

-- Updated timestamp trigger
CREATE OR REPLACE FUNCTION update_updated_at()
RETURNS TRIGGER AS $$
BEGIN
  NEW.updated_at = NOW();
  RETURN NEW;
END;
$$ LANGUAGE plpgsql;

CREATE TRIGGER users_updated_at
  BEFORE UPDATE ON users
  FOR EACH ROW
  EXECUTE FUNCTION update_updated_at();
```

### Indexing Strategy

```sql
-- B-Tree: Equality, range, sorting (default)
CREATE INDEX idx_users_email ON users(email);

-- Composite: Leftmost prefix rule
-- Supports: (user_id), (user_id, created_at)
-- Does NOT support: (created_at) alone
CREATE INDEX idx_orders_user_date ON orders(user_id, created_at DESC);

-- Partial: Reduce index size
CREATE INDEX idx_active_users ON users(email)
  WHERE status = 'active';

-- GIN for JSONB: Containment queries
CREATE INDEX idx_metadata ON users USING GIN (metadata jsonb_path_ops);

-- Expression: Specific JSONB field
CREATE INDEX idx_user_role ON users ((metadata->>'role'));

-- Full-text search
CREATE INDEX idx_search ON products USING GIN (to_tsvector('english', name || ' ' || description));
```

### JSONB Usage

```sql
-- Good: Dynamic attributes, rarely queried fields
CREATE TABLE products (
  id UUID PRIMARY KEY,
  name TEXT NOT NULL,
  price NUMERIC(19,4) NOT NULL,
  category TEXT NOT NULL,           -- Extracted: frequently queried
  attributes JSONB DEFAULT '{}'     -- Dynamic: color, size, specs
);

-- Query with containment
SELECT * FROM products
WHERE category = 'electronics'              -- B-Tree index
  AND attributes @> '{"brand": "Apple"}';   -- GIN index

-- Query specific field
SELECT * FROM products
WHERE attributes->>'color' = 'black';       -- Expression index

-- Update JSONB field
UPDATE products
SET attributes = attributes || '{"featured": true}'
WHERE id = '...';
```

### Query Optimization

```sql
-- Always use EXPLAIN ANALYZE
EXPLAIN ANALYZE
SELECT u.*, COUNT(o.id) as order_count
FROM users u
LEFT JOIN orders o ON o.user_id = u.id
WHERE u.status = 'active'
GROUP BY u.id
ORDER BY u.created_at DESC
LIMIT 20;

-- Watch for:
-- ❌ Seq Scan on large tables → Add index
-- ❌ Sort → Use index for ordering
-- ❌ Nested Loop with many rows → Consider JOIN order
-- ❌ Hash Join on huge tables → Add indexes
```

### Connection Pooling

```typescript
// PgBouncer or built-in pool
import { Pool } from 'pg';

const pool = new Pool({
  max: 20,                      // Max connections
  idleTimeoutMillis: 30000,     // Close idle connections
  connectionTimeoutMillis: 2000, // Fail fast
});

// Connection count formula:
// connections = (cores * 2) + effective_spindle_count
// Usually 10-30 is enough
```

---

## Redis

### Data Structure Selection

| Use Case | Structure | Example |
|----------|-----------|---------|
| Cache objects | String | `user:123` → JSON |
| Counters | String + INCR | `views:article:456` |
| Sessions | Hash | `session:abc` → {userId, ...} |
| Leaderboards | Sorted Set | `scores` → {userId: score} |
| Queues | List/Stream | `tasks` → LPUSH/RPOP |
| Unique sets | Set | `online_users` |
| Real-time | Pub/Sub/Stream | Notifications |

### Key Naming

```
# Format: <entity>:<id>:<attribute>
user:123:profile
user:123:settings
order:456:items
session:abc123

# Use colons for hierarchy
# Enables pattern matching with SCAN
SCAN 0 MATCH "user:*:profile" COUNT 100
```

### TTL Strategy

```typescript
const TTL = {
  SESSION: 24 * 60 * 60,      // 24 hours
  CACHE: 15 * 60,             // 15 minutes
  RATE_LIMIT: 60,             // 1 minute
  LOCK: 30,                   // 30 seconds
};

// Set with TTL
await redis.set(`cache:user:${id}`, JSON.stringify(user), 'EX', TTL.CACHE);

// Check TTL
const remaining = await redis.ttl(`cache:user:${id}`);
```

---

## Caching Patterns

### Cache-Aside (Lazy Loading)

```typescript
async function getUser(id: string): Promise<User> {
  const cacheKey = `user:${id}`;

  // 1. Check cache
  const cached = await redis.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }

  // 2. Cache miss → Query database
  const user = await db.user.findUnique({ where: { id } });
  if (!user) {
    throw new NotFoundError('User not found');
  }

  // 3. Populate cache
  await redis.set(cacheKey, JSON.stringify(user), 'EX', 900);

  return user;
}
```

### Write-Through

```typescript
async function updateUser(id: string, data: UpdateInput): Promise<User> {
  // 1. Update database
  const user = await db.user.update({
    where: { id },
    data,
  });

  // 2. Update cache immediately
  await redis.set(`user:${id}`, JSON.stringify(user), 'EX', 900);

  return user;
}
```

### Cache Invalidation

```typescript
async function deleteUser(id: string): Promise<void> {
  // 1. Delete from database
  await db.user.delete({ where: { id } });

  // 2. Invalidate cache
  await redis.del(`user:${id}`);

  // 3. Invalidate related caches
  const keys = await redis.keys(`user:${id}:*`);
  if (keys.length > 0) {
    await redis.del(...keys);
  }
}
```

### Cache Stampede Prevention

```typescript
async function getUserWithLock(id: string): Promise<User> {
  const cacheKey = `user:${id}`;
  const lockKey = `lock:user:${id}`;

  // Check cache
  const cached = await redis.get(cacheKey);
  if (cached) {
    return JSON.parse(cached);
  }

  // Try to acquire lock
  const acquired = await redis.set(lockKey, '1', 'EX', 10, 'NX');

  if (!acquired) {
    // Another process is loading, wait and retry
    await sleep(100);
    return getUserWithLock(id);
  }

  try {
    // Double-check cache (another process might have populated it)
    const rechecked = await redis.get(cacheKey);
    if (rechecked) {
      return JSON.parse(rechecked);
    }

    // Load from database
    const user = await db.user.findUnique({ where: { id } });
    await redis.set(cacheKey, JSON.stringify(user), 'EX', 900);
    return user;
  } finally {
    await redis.del(lockKey);
  }
}
```

### Cache Penetration Prevention

```typescript
async function getUserSafe(id: string): Promise<User | null> {
  const cacheKey = `user:${id}`;

  const cached = await redis.get(cacheKey);

  // Check for cached null
  if (cached === 'NULL') {
    return null;
  }

  if (cached) {
    return JSON.parse(cached);
  }

  const user = await db.user.findUnique({ where: { id } });

  if (!user) {
    // Cache null with short TTL
    await redis.set(cacheKey, 'NULL', 'EX', 60);
    return null;
  }

  await redis.set(cacheKey, JSON.stringify(user), 'EX', 900);
  return user;
}
```

---

## Tiered Storage

```
┌─────────────────────────────────────────────────┐
│                   Application                    │
└─────────────────────────────────────────────────┘
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
   ┌─────────┐    ┌─────────┐    ┌─────────┐
   │  Redis  │    │ Postgres │    │ Archive │
   │  (Hot)  │    │  (Warm)  │    │  (Cold) │
   └─────────┘    └─────────┘    └─────────┘

   < 1ms          ~10ms           ~100ms+
   Active data    Recent data     Historical
   Memory         SSD             Object storage
```

### Partitioning for Cold Data

```sql
-- Partition by date range
CREATE TABLE orders (
  id UUID NOT NULL,
  user_id UUID NOT NULL,
  total NUMERIC(19,4) NOT NULL,
  created_at TIMESTAMPTZ NOT NULL
) PARTITION BY RANGE (created_at);

-- Create partitions
CREATE TABLE orders_2025_q1 PARTITION OF orders
  FOR VALUES FROM ('2025-01-01') TO ('2025-04-01');

CREATE TABLE orders_2025_q2 PARTITION OF orders
  FOR VALUES FROM ('2025-04-01') TO ('2025-07-01');

-- Archive old data
CREATE TABLE orders_archive (LIKE orders INCLUDING ALL);

-- Move old data to archive
WITH moved AS (
  DELETE FROM orders
  WHERE created_at < NOW() - INTERVAL '1 year'
  RETURNING *
)
INSERT INTO orders_archive SELECT * FROM moved;
```

---

## Transactions

### ACID Compliance

```typescript
// Use transactions for multi-table operations
async function transferFunds(fromId: string, toId: string, amount: number) {
  await db.$transaction(async (tx) => {
    // Deduct from source
    const from = await tx.account.update({
      where: { id: fromId },
      data: { balance: { decrement: amount } },
    });

    if (from.balance < 0) {
      throw new Error('Insufficient funds');
    }

    // Add to destination
    await tx.account.update({
      where: { id: toId },
      data: { balance: { increment: amount } },
    });
  });
}
```

### Optimistic Locking

```sql
-- Add version column
ALTER TABLE products ADD COLUMN version INT DEFAULT 1;

-- Update with version check
UPDATE products
SET
  stock = stock - 1,
  version = version + 1
WHERE id = $1 AND version = $2
RETURNING *;

-- If no rows returned, concurrent modification occurred
```

---

## Checklist

```markdown
## Schema
- [ ] UUID or BIGSERIAL for primary keys
- [ ] TIMESTAMPTZ for all timestamps
- [ ] NUMERIC for money, not FLOAT
- [ ] CHECK constraints for enums
- [ ] Foreign keys with ON DELETE

## Indexing
- [ ] Index for each WHERE clause pattern
- [ ] Composite indexes match query order
- [ ] GIN index for JSONB containment
- [ ] EXPLAIN ANALYZE for slow queries

## Caching
- [ ] Cache-aside as default pattern
- [ ] TTL on all cached data
- [ ] Cache invalidation on writes
- [ ] Stampede/penetration protection

## Operations
- [ ] Connection pooling configured
- [ ] Slow query logging enabled
- [ ] Backup and recovery tested
- [ ] Partition strategy for growth
```

---

## See Also

- [reference/postgresql.md](reference/postgresql.md) — PostgreSQL deep dive
- [reference/redis.md](reference/redis.md) — Redis patterns
- [reference/caching.md](reference/caching.md) — Caching strategies

© majiayu000 · MIT · majiayu000/spellbook

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

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

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

database-patterns OrchestKit Скилл database-patterns помогает проектировать схемы, создавать миграции Alembic и находить расхождения между версиями базы. Включается при работе с SQL и NoSQL. CX Codex +1 238установок database-patterns c0x12c Скилл database-patterns для Claude Code и Codex, задаёт правила проектирования БД: типы колонок, UUID-ключи, мягкое удаление и шаблоны миграций. Агент использует их при создании таблиц и репозиториев. CX Codex +1 ★ 111звёзд репо database-expert travisjneuman Скилл database-expert для Claude Code помогает проектировать схемы и разбирать запросы к базам данных. Подключается к задачам администрирования PostgreSQL, MongoDB и Redis. CX Codex +1 255установок database-schema-design aj-geddes Скилл database-schema-design помогает проектировать схемы реляционных баз данных, нормализовать таблицы и выстраивать связи. Пригодится при создании моделей данных для PostgreSQL и MySQL. CX Codex +1 599установок database-schema-designer OneWave-AI Скилл database-schema-designer проектирует реляционные и документные схемы баз данных по требованиям или коду проекта. Помогает составить таблицы, связи, строгие ограничения и миграции. CX Codex +1 432установок discover-database rand Скилл discover-database подбирает инструкции по SQL, NoSQL, оптимизации запросов и кэшированию под текущую задачу агента. CX Codex +1 125установок database-management-patterns manutej Скилл database-management-patterns для Claude Code — справочник по PostgreSQL и MongoDB для проектирования схем, работы с индексами, транзакциями, репликацией и шардированием. CX Codex +1 467установок database-design-patterns curiositech Скилл database-design-patterns проектирует схемы реляционных БД: нормализует таблицы до 3NF, подбирает типы индексов и планирует миграции без простоя сервиса. CX Codex +1 152установок

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

Весь набор →
technical-spec Скилл technical-spec помогает готовить технические спецификации, RFC и архитектурные решения (ADR) по жёстким правилам оформления. CX Codex +1 245установок product-ux-expert Скилл product-ux-expert для проверки интерфейсов по эвристикам Нильсена, построения карт пути пользователя и аудита доступности по WCAG 2.2 AA. CX Codex +1 212установок prd-master Скилл prd-master помогает писать техспецификации, юзер-стори и критерии приёмки. Структурирует требования по RICE и MoSCoW и задаёт измеримые цели. CX Codex +1 166установок observability-sre Скилл observability-sre помогает настраивать наблюдаемость, SLO и процессы реагирования на инциденты. Подключайте его при работе с Prometheus, Grafana и OpenTelemetry. CX Codex +1 165установок clash-doctor Скилл clash-doctor диагностирует сетевые сбои в Clash Verge и mihomo, правит маршруты для ИИ-инструментов и настраивает исключения TUN. CX Codex +1 142установок trip-planner Скилл trip-planner для Claude Code составляет подробные планы поездок по дням: с адресами, временем в пути и вечерними списками сборов. Планирует отпуска и автопутешествия. CX Codex +1 134установок auth-security Скилл auth-security для Claude Code задаёт правила безопасной авторизации по OAuth 2.1 и RFC 9700: PKCE, ротацию refresh-токенов и строгую проверку JWT. CX Codex +1 117установок devops-excellence Скилл devops-excellence задаёт строгие правила DevOps: запрещает root в контейнерах, убирает секреты из сборки и настраивает OIDC в GitHub Actions. CX Codex +1 114установок

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

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