🧭 Что это

Database Migration Patterns — это набор проверенных практик и готовых сценариев для безопасного управления изменениями схемы и данных в реляционных базах данных (PostgreSQL, MySQL) и популярных ORM (Prisma, Drizzle, Django, TypeORM, golang-migrate). Skill помогает избежать простоев, блокировок таблиц и потери данных при деплое миграций в production-среде.

⚙️ Как работает

🔐 Базовые принципы

• Каждое изменение — миграция. Никогда не вносите правки в production-базу вручную.
• Миграции только вперёд. Откат — это новая миграция, а не запуск DOWN (за исключением явных rollback-сценариев).
• DDL и DML разделены: никогда не смешивайте изменение схемы (ALTER TABLE) и модификацию данных (UPDATE) в одной миграции.
• Тестируйте на production-размере данных. Миграция, работающая на 100 строк, может заблокировать таблицу на 10M.
• Миграции неизменяемы после применения в production. Не редактируйте уже выполненную миграцию.

🛡️ Чеклист безопасности перед выполнением

• ✅ Миграция содержит UP и DOWN (или явно помечена как неоткатываемая).
• ✅ Нет полных блокировок таблиц на больших объёмах (CREATE INDEX без CONCURRENTLY, ALTER TABLE ... SET NOT NULL без предварительного backfill).
• ✅ Новые столбцы — nullable или с DEFAULT. Никогда не добавляйте NOT NULL без значения по умолчанию.
• ✅ Индексы создаются через CREATE INDEX CONCURRENTLY для существующих таблиц.
• ✅ Data backfill вынесен в отдельную миграцию после изменения схемы.
• ✅ Протестировано на копии production-данных.
• ✅ План отката задокументирован.

📘 PostgreSQL: безопасные паттерны

➕ Добавление столбца

Хорошо:

ALTER TABLE users ADD COLUMN avatar_url TEXT;               -- nullable, без блокировки
ALTER TABLE users ADD COLUMN is_active BOOLEAN NOT NULL DEFAULT true;  -- Postgres 11+, мгновенно

Плохо:

ALTER TABLE users ADD COLUMN role TEXT NOT NULL;   -- блокирует таблицу и перезаписывает все строки

🧵 Добавление индекса без блокировки

Плохо (блокирует запись):

CREATE INDEX idx_users_email ON users (email);

Хорошо (разрешена параллельная запись):

CREATE INDEX CONCURRENTLY idx_users_email ON users (email);
-- НЕ выполняется внутри транзакционного блока!

🔁 Переименование столбца (expand-contract)

Никогда не переименовывайте столбец напрямую в production. Используйте многошаговый паттерн:

1. Expand — добавить новый столбец (display_name).
2. Backfill — перенести данные отдельной миграцией: UPDATE users SET display_name = username WHERE display_name IS NULL;.
3. Deploy — обновить код приложения на чтение/запись обоих столбцов.
4. Contract — удалить старый столбец после того, как приложение перестанет его использовать.

❌ Удаление столбца

Удалять можно только после того, как все ссылки в коде приложения убраны и деплой выполнен. В следующей миграции:

ALTER TABLE orders DROP COLUMN legacy_status;

Для Django используйте SeparateDatabaseAndState, чтобы сначала изменить модель, а столбец удалить позже.

📦 Массовые обновления (data migration)

Плохо — одна транзакция на все строки (блокирует таблицу):

UPDATE users SET normalized_email = LOWER(email);

Хорошо — пакетная обработка с SKIP LOCKED:

DO $$
DECLARE batch_size INT := 10000; rows_updated INT;
BEGIN
  LOOP
    UPDATE users SET normalized_email = LOWER(email)
    WHERE id IN (SELECT id FROM users WHERE normalized_email IS NULL LIMIT batch_size FOR UPDATE SKIP LOCKED);
    GET DIAGNOSTICS rows_updated = ROW_COUNT;
    EXIT WHEN rows_updated = 0;
    COMMIT;
  END LOOP;
END $$;

🛠️ Инструменты и их команды

Prisma (TypeScript/Node.js)

# Создать миграцию из схемы
npx prisma migrate dev --name add_user_avatar
# Применить в production
npx prisma migrate deploy
# Сбросить БД (только dev)
npx prisma migrate reset
# Сгенерировать клиент после изменений
npx prisma generate

Для операций, неподдерживаемых Prisma (например, CONCURRENTLY), создаётся пустая миграция и SQL редактируется вручную:

npx prisma migrate dev --create-only --name add_email_index

Drizzle (TypeScript/Node.js)

npx drizzle-kit generate   # из схемы
npx drizzle-kit migrate    # применить
npx drizzle-kit push       # только dev, без файла миграции

Django (Python)

python manage.py makemigrations
python manage.py migrate
python manage.py showmigrations
python manage.py makemigrations --empty app_name -n description   # для кастомного SQL

Пример data migration внутри Django:

def backfill_display_names(apps, schema_editor):
    User = apps.get_model("accounts", "User")
    batch_size = 5000
    while users.exists():
        batch = list(users[:batch_size])
        for user in batch:
            user.display_name = user.username
        User.objects.bulk_update(batch, ["display_name"], batch_size=batch_size)

golang-migrate (Go)

migrate create -ext sql -dir migrations -seq add_user_avatar
migrate -path migrations -database "$DATABASE_URL" up
migrate -path migrations -database "$DATABASE_URL" down 1
migrate -path migrations -database "$DATABASE_URL" force VERSION   # исправить dirty-статус

Пример файла миграции:

-- 000003_add_user_avatar.up.sql
ALTER TABLE users ADD COLUMN avatar_url TEXT;
CREATE INDEX CONCURRENTLY idx_users_avatar ON users (avatar_url) WHERE avatar_url IS NOT NULL;

🚀 Zero-downtime migration (expand-contract)

Стратегия для критических изменений, не допускающих простоя:

• Фаза 1 (EXPAND): добавить новый столбец/таблицу (nullable или с default). Деплой приложения, которое пишет и в старый, и в новый атрибут.
• Фаза 2 (MIGRATE): запустить backfill существующих данных. Приложение читает из нового, пишет в оба.
• Фаза 3 (CONTRACT): убрать старый столбец/таблицу отдельной миграцией, когда приложение полностью перешло на новое поле.

Пример временного графика:

• День 1: миграция new_status (nullable). Деплой app v2 (пишет в оба поля).
• День 2: backfill старых строк.
• День 3: деплой app v3 (читает только new_status).
• День 7: миграция удаляет старый status.

✅ Когда использовать

• При каждом изменении схемы БД (добавление/удаление таблиц, столбцов, индексов).
• Для выполнения data migration (backfill, трансформация данных).
• При планировании изменений без остановки сервиса.
• При настройке инструментов миграции в новом проекте.

⚠️ Важно знать: анти-паттерны

Всегда помните: миграция — это код. Она должна быть версионирована, рецензируема и тестируема.

Синхронизируйте навыки в Claude Cowork, Claude Code, Codex и другие.

Установка одной командой.

npx skillfish add affaan-m/everything-claude-code database-migrations