Міграції

Звичайні TypeScript up/down. hopak migrate new · up · down · status.

Еволюція схеми з історією та відкатом. Кожна міграція — один .ts файл у app/migrations/ з функціями up та down.

Підкоманди

Створення міграцій

hopak sync — для dev-завантаження: він виконує CREATE TABLE IF NOT EXISTS при першому старті й більше нічого. Щойно вам потрібно додати колонку, управління беруть на себе міграції.

hopak migrate init
# → Created app/migrations/20260422T153012345_init.ts (CREATE TABLE for each model)

hopak migrate new add_role_to_user
# → Created app/migrations/20260422T160100_add_role_to_user.ts (empty up/down skeleton)

Заповніть скелет:

import type { MigrationContext } from '@hopak/core';

export const description = 'Add role column to user';

export async function up(ctx: MigrationContext): Promise<void> {
  await ctx.sql`ALTER TABLE users ADD COLUMN role TEXT DEFAULT 'user'`;
}

export async function down(ctx: MigrationContext): Promise<void> {
  await ctx.sql`ALTER TABLE users DROP COLUMN role`;
}

Застосування, інспекція, відкат

hopak migrate up              # applies pending
hopak migrate up --dry-run    # preview without touching DB
hopak migrate status          # applied / pending / missing
hopak migrate down            # rollback last (or --steps N)

ctx.db всередині up/down — повний клієнт Hopak; дата-міграції (заповнити нову колонку, переписати рядки) живуть у тому ж файлі, що і їхній DDL.

Транзакційний контракт

• SQLite / Postgres: кожна міграція виконується всередині db.transaction().
• MySQL: DDL робить auto-commit, тому міграції виконуються без зовнішньої транзакції; ідіома — один DDL на файл, щоб збої залишалися відновлюваними.

Коли app/migrations/ існує, hopak sync відмовляється виконуватися — еволюція схеми живе виключно у міграціях. До цього моменту sync — усе ще найшвидший шлях від hopak new до робочого ендпойнта.

Якщо ви зміните колонку моделі, все ще перебуваючи на sync, наступний hopak dev виведе попередження про дрейф, що вказує на hopak migrate init — природний момент для переходу на міграції.