Плейбуки міграцій
1) Класифікація міграцій
Схеми БД: додавання/зміна колонок, індекси, шардування, зміна типу ключів.
Дані: масовий backfill/cleanup, нормалізація, ретеншн/архівація.
Сервіси та API: зміна ендпоінтів, версіонування, рефакторинг контрактів.
Черги/шини: переїзд топіків, зміна ключів партіонування, формат подій.
Інфраструктура: перехід в новий кластер/K8s/хмара/регіон, зміна секретів/KMS.
Сховища та аналітика: зміна рушія (OLTP/OLAP), формат/партіонування датасетів.
Безпека/комплаєнс: ротація ключів, шифрування «на льоту», гео-локалізація даних.
2) Принципи успішної міграції
1. Expand → Migrate → Contract. Спочатку розширюємо схему/поведінку (сумісно), потім переносимо дані/трафік, потім прибираємо старе.
2. Shadow & Dual. Тіньова перевірка (shadow read/write) і подвійний запис для валідації.
3. Фіча-прапори і «червона кнопка». Швидке відключення, покрокове включення (персентиль/тенанти/регіони).
4. Ідемпотентність і повторюваність. Скрипти та завдання можна перезапускати без побічних ефектів.
5. Спостережуваність перш змін. Дашборди/алерти заздалегідь, маркери міграції в логах/трейсах.
6. Відкат документовано. Runbook відкату так само докладний, як і план вперед.
7. Міні-партії і паузи. Мігруємо невеликими порціями, перевіряючи SLI і бізнес-інваріанти.
3) Інвентаризація та аналіз залежності
Карта споживачів: сервіси, джоби, звіти, зовнішні партнери, BI/ETL, вебхуки.
Контракти та схеми: версії API/подій, сумісність backward/forward.
Доступи/секрети: хто читає/пише, де кеші/репліки.
Інваріанти домену: унікальність, баланс, ідемпотентність, звітна доба.
Обсяги/швидкості: розмір даних, RPS, пікові вікна, RPO/RTO.
4) Канонічний шаблон плейбука (YAML-скелет)
yaml playbook: "migrate-orders-to-v2"
owner: "orders-team"
stakeholders: ["platform", "data", "security", "support"]
change_type: ["schema", "data", "api"]
risk_level: "high"
preconditions:
- "Dashboards ready: latency/error/lag"
- "Runbook rollback validated on stage"
- "Backups verified (restore tested)"
plan:
phase_1_prepare:
steps:
- "Add new nullable columns (expand)"
- "Deploy code with dual-write (flag off)"
- "Enable CDC stream to target"
phase_2_shadow:
steps:
- "Shadow-read v2, compare with v1 (1%)"
- "Fix discrepancies; iterate"
phase_3_dual_write:
steps:
- "Enable dual-write (10%→50%→100%)"
- "Start backfill in batches (size=10k, sleep=200ms)"
phase_4_cutover:
steps:
- "Switch reads to v2 by tenants (canary)"
- "Monitor SLI 30m; expand scope"
phase_5_contract:
steps:
- "Drop old indices/columns after T+14d"
- "Disable old topic/api; update docs/SDK"
guardrails:
abort_if:
- "error_rate > 0. 5% for 5m"
- "p95 > baseline1. 5 for 10m"
- "data_mismatch > 0. 01%"
rollback:
steps:
- "Flip flag: reads back to v1"
- "Stop backfill; continue dual-write to v1"
- "Replay missed events (DLQ→v1)"
validation:
checks:
- "Row counts match within epsilon"
- "Business invariants hold (balances, limits)"
comms:
- channel: "on-call-bridge"
- status_updates: "T-24h, T-1h, start, cutover, finish"
window: "low-traffic Sun 02:00–05:00 UTC"5) Патерни міграцій
5. 1 Схеми БД (RDBMS/NoSQL)
Додавайте - не змінюйте. Нові nullable колонки/індекси → код читає старе і нове.
Онлайн-перебудова. Використовуйте онлайн-індекси/паралельні DDL.
Версії серіалізації. Версіонуйте payload в колонках JSON/Proto/Avro.
Міграція ключів. При зміні PK - тимчасова таблиця відповідностей + тригер/CDC.
5. 2 Дані (backfill/cleanup)
CDC + backfill. Спочатку потік змін (щоб не відставати), потім пакетний backfill.
Партії та дедлайни. Малі батчі з контролем лагів, чекпойнти і повторний запуск.
Ідемпотентні апдейти. Upsert за природними ключами/версіями.
5. 3 Події та черги
Версіонування подій.'event _ type @vN', консьюмери ігнорують незнайомі поля.
Переїзд топиків. Подвійна публікація, споживачі читають з обох до стабілізації; потім «різання» старого.
Partition key. Міграція ключа - через перевидання з картою відповідностей та ідемпотентністю.
5. 4 Сервіси та API
Blue/Green/Canary. Прогрів пулу, частковий трафік, швидкий відкат.
Фіча-прапори. За тенантами/регіонами/відсотками, спостережуване включення.
Контракти. CDC-контракти і тести сумісності - до перемикання.
5. 5 Регіони/клауди
Гео-подвійний запис. Дані записуються в два регіони; читання - по близькості.
State transfer. Знімок + реплікація; «червона лінія» RPO, перевалка DNS/Anycast.
Юрисдикції. Згоди/локалізація даних, списки «заборонених» для виносу наборів.
6) Фази виконання (детально)
1. Підготовка
Дашборди, альберти, ліміти, фіча-прапори, бекапи з тестом відновлення, прогін на стейджі.
2. Shadow (тіньова перевірка)
Дзеркалимо запити/записи в нову систему без впливу на користувачів. Порівнюємо відповіді/стани.
3. Dual-write / Dual-read
Пишемо в обидві сторони. Читання - поступово переводимо на нову систему. Логи невідповідностей аналізуються.
4. Backfill
Довантажуємо історичні дані партіями. Контролюємо лаг CDC, стежимо за навантаженням на сторідж/кеш.
5. Cutover (перемикання)
Канарім по сегментах (тенанти/регіони/відсотки). Підтримуємо швидкий відкат.
6. Contract (очищення)
Відрубуємо старі шляхи, видаляємо застарілі поля/індекси/топіки після «періоду безпеки».
7. Верифікація і ретро
Звіт, метрики, уроки, оновлення плейбука/чек-листів.
7) Спостережуваність і SLO під час міграції
Технічні SLI: p50/p95/p99, error rate, retry/timeout, utilization, lag CDC, глибина черг.
Бізнес-SLI: успіх транзакцій/конверсій, інваріанти (баланси, ліміти, дублікати).
Спеціальні мітки: `migration_id`, `phase`, `tenant`, `flag_state`.
Алерти-охоронці: пороги на хвости і помилки, «авто-стоп» (abort) по SLO.
Порівняльні панелі: v1 vs v2, «дельта» за ключовими метриками.
8) Відкат та аварійні сценарії
Логічний відкат: прапори/маршрутизація трафіку назад, заморожування backfill.
Дані: «компенсації» (Saga), реплей подій, DLQ → вихідна система.
Секрети/ключі: повернення на попередній ключ/сертифікат (dual-key).
DNS/трафік: «зворотний дрифт» Anycast/ALB, TTL короткий у вікно міграції.
Комунікації: заздалегідь узгоджений канал і формат статусів.
9) Безпека, приватність, комплаєнс
Мінімізація даних. Переносимо тільки необхідні поля; профілі анонімізації на копії.
Криптографія. Шифрування «на проводі» і «в спокої», ротація KMS; журнал операцій з ключами.
Доступи за часом. Тимчасові ролі для міграційних джобів, відбір прав після завершення.
Сліди. Маскування ПД в логах/трейсах, обмеження експорту.
10) Управління змінами та комунікації
RACI: хто стверджує, хто виконує, хто інформується.
Freeze-періоди: заборона нерелевантних релізів у вікно міграції.
Статуси: T-24h, T-1h, старт, канарінг, cutover, фініш, пост-морем.
Зовнішні партнери: вікна сумісності, контрактні листи, тестова пісочниця.
11) Шаблони runbook'ів
11. 1 Backfill (псевдокод)
for batch in paginate(ids, size=10_000):
try:
rows = read_v1(batch)
upsert_v2 (rows) # idempotently mark_checkpoint (batch. end)
sleep(jitter_ms(100..300))
except Throttle:
sleep (5s) # backpressure respect except Fatal as e:
alert("backfill-failed", e, context=batch)
abort_if_needed()11. 2 Proverka一致nosti (снепшот/вибірка)
sample = random_ids(n=10_000, stratify=tenant,timestamp)
v1 = fetch_v1(sample); v2 = fetch_v2(sample)
assert schema_compatible(v2)
assert key_invariants_hold (v1, v2) # sum, statuses, versions mismatch_rate = diff (v1, v2). rate()
abort_if(mismatch_rate > 0. 0001)11. 3 Перемикання читань
flag. enable("read_from_v2", segment="tenants: cohort_A")
monitor(30m)
if SLO_ok(): expand_segment()
else: rollback_segment()12) Анти-патерни
«Великий вибух» замість expand-migrate-contract.
Backfill без CDC → вічне наздоганяння і дрейф.
Відсутність ідемпотентності → дублі/брудні дані.
Ручні кроки без скриптів → людські помилки.
Міграція без дашбордів/охоронців → «сліпий політ».
Непідтверджений відкат → відкат не працює, коли потрібен.
Ігнорування споживачів (BI/партнери) → «зламані» звіти/інтеграції.
13) Чек-лист архітектора
1. Визначено мету, межі, тип міграції та інваріанти результату?
2. Карта споживачів і контрактів складена, тести сумісності зелені?
3. Підготовлені дашборди, алерти, мітки'migration _ id', SLO/guardrails задані?
4. Реалізовані shadow і/або dual-write, backfill ідемпотентний?
5. Є практикований rollback runbook, перевірки відновлення з бекапа?
6. Вікно/координація/комунікації узгоджені, freeze включений?
7. Покроковий план з канарингом і критеріями розширення/зупинки готовий?
8. Безпека/комплаєнс: ключі, доступи, PII-санітарія?
9. Документація/SDK/спеки оновлюються в тому ж релізному циклі?
10. Пост-морем і оновлення плейбука після завершення заплановані?
Висновок
Плейбуки міграцій - це архітектурна практика управління ризиком: дрібні оборотні кроки, прозорі метрики, готовий відкат і дисципліна «expand-migrate-contract». Дотримуючись описаних шаблонів, ви мігруєте схеми, дані, сервіси і регіони без простою і сюрпризів, зберігаючи інваріанти бізнесу і довіру користувачів.