Миграции базы данных

Это руководство посвящено собственной базе данных CMS: где хранится история схемы, как менять схему и как применять изменения к локальной базе, развёрнутой базе и базам отдельных сайтов. Запускайте каждую команду из корня репозитория.

Где что лежит

Путь	Что это
`backend/prisma/migrations/`	SQL-миграции Prisma, по одному каталогу на миграцию. `20260908000000_init` — базовая схема новой установки: вся схема и её начальные строки. Источник истины для истории схемы, включая собственные ограничения и обязательные начальные строки.
`backend/migrations-wrangler/`	Зеркало этих миграций для D1 (`0001_init.sql` для базовой схемы, затем по одному файлу на каждую следующую миграцию). Генерируется — никогда не редактируйте его вручную. Wrangler применяет эти файлы к D1.
`backend/prisma/prod.prisma`, `local.prisma`, `site.prisma`, `eav.prisma`, `tables.prisma`	Фрагменты схемы. Редактируйте их.
`backend/prisma/schema.prisma`	Собирается из `prod.prisma` + `site.prisma` + `eav.prisma` + `tables.prisma` скриптом `scripts/build-prisma-schema.mjs`. Он хранится в репозитории, но это результат сборки: правка, внесённая прямо в него, перезаписывается при следующей сборке.
`backend/prisma/schema.local.prisma`	Та же сборка поверх `local.prisma`, используется для создания миграций. Игнорируется git.
`backend/tenant-migrations/`	Схема, с которой начинается новая база данных сайта (`0001_tenant_schema.sql`), плюс дельты в `deltas/`, которые доводят существующие базы данных сайтов до актуального состояния. Дельт пока нет. Нужна, только если вы используете `npm run provision:site`.

После первого релиза миграции только дополняются. Никогда не редактируйте и не удаляйте выпущенную миграцию. Исправляйте её новой миграцией.

До первого релиза

Dee Wan ещё не выпущен, поэтому поддерживать обновление существующих установок пока не требуется. До первого релиза изменения схемы вносят в базовую миграцию, а не создают новую: фрагмент, 20260908000000_init, его зеркало 0001_init.sql и базовая схема сайтов 0001_tenant_schema.sql меняются вместе, и npm run migrate:check, npm run prisma:drift и npm run tenant:schema:check должны проходить.

Первый выпуск начинается с новых баз данных. В нём нет SQL для обновления баз, созданных более ранней сборкой, и нет дельт сайтов. Правка базовой схемы меняет схему сайтов без новой дельты, поэтому npm run tenant:schema её отклоняет. Перегенерируйте схему командой npm run tenant:schema -- --allow-no-delta. После первого выпуска каждое изменение схемы — это новая миграция по шагам ниже.

Локальная база, созданная по старой базовой миграции, такое изменение не получит. Пересоздайте её: остановите локальный стенд, удалите backend/.wrangler/state, затем снова выполните npm run local:migrate и npm run local:seed. Это удаляет все локальные сайты, записи и загрузки.

Изменение схемы

До первого релиза обновляйте базовую схему, как описано выше. Шаги ниже применяются после релиза.

Отредактируйте фрагмент, в котором находится модель (site.prisma, eav.prisma или tables.prisma).
Пересоберите schema.prisma и клиент Prisma:
Окно терминала
```
npm run prisma:generate
```
Примените к локальной базе данных всё, что уже существует, затем создайте новую миграцию:
Окно терминала
```
npm run local:migrate
npm run local:migrate -- initial --create-migration
```
Создание миграции отключено, пока вы не передадите --create-migration, поэтому обычное применение не создаёт миграцию на основе схемы, которая разошлась с базой. С этим флагом, и только когда все существующие миграции уже применены локально, команда запускает prisma migrate dev --create-only, которая создаёт новый каталог в backend/prisma/migrations/, а затем применяет эту миграцию к локальной базе данных. Она использует отслеживаемую локальную конфигурацию (backend/wrangler.dev.jsonc), поэтому работает в клоне репозитория, где ещё не запускали установку Dee Wan.

Оставьте в этой команде слово initial. --create-migration без него сейчас отклоняется с подсказкой по использованию команды.
Прочитайте сгенерированный SQL, прежде чем его коммитить. Миграция, созданная на основе схемы, которая разошлась с базой данных, может содержать операторы DROP TABLE, которых никто не планировал.

Заново сгенерируйте зеркало для D1 и проверьте результат:

npm run migrate:sync          # writes backend/migrations-wrangler/ from the Prisma migrations
npm run migrate:check         # fails if the mirror and the migrations disagree
npm run prisma:drift          # fails if schema.prisma no longer describes what the migrations build

Если вы используете базы данных отдельных сайтов, заново сгенерируйте и их схему:
Окно терминала
```
npm run tenant:schema         # rewrites the per-site bootstrap schema
npm run tenant:schema:check   # fails until every new table has a placement
```
Миграция, добавляющая таблицу, не проходит tenant:schema:check, пока для таблицы не задано размещение в backend/src/lib/tenancy/placement.ts.

Миграции, которая меняет то, что хранят существующие базы сайтов, нужна ещё и дельта. Запишите SQL, который обновляет такую базу до новой схемы, в backend/tenant-migrations/deltas/NNNN_<name>.sql со следующим номером, до запуска npm run tenant:schema. Для нового столбца или индекса это SQL самой миграции. npm run tenant:schema отказывается принять изменённую схему сайтов без новой дельты и называет файл, который нужно создать. Передавайте --allow-no-delta, только если изменению дельта не нужна.
Добавляйте в один коммит миграцию Prisma, её файл-зеркало, любую дельту и все изменения схемы сайтов.

Применение миграций

Куда	Команда	Примечания
Локальный стенд (без аккаунта Cloudflare)	`npm run local:migrate`	Использует `backend/wrangler.dev.jsonc`, который есть в каждом клоне. Учётные данные не нужны.
Локальное зеркало установленной конфигурации	`npm run migrate:d1:local`	Читает `backend/wrangler.jsonc`, который пишет `setup` и который игнорирует git, поэтому не работает в клоне, где ещё не запускали установку. Используйте его вместе с `npm run dev:install --workspace backend`.
Развёрнутая управляющая база данных	`npm run migrate:d1`	Нужен `CLOUDFLARE_API_TOKEN`. Перед запуском выводит конфигурацию и базу данных, которую собирается мигрировать. Добавьте `-- --config <file>` для установки, у которой конфигурация не `backend/wrangler.jsonc`.
Существующие базы данных сайтов	`npm run tenant:upgrade`	Только если вы запускали `npm run provision:site`. `-- --plan` показывает, чего не хватает каждому сайту, ничего не записывая.

Новой установке ничего из этого не нужно: npm run setup применяет схему сам.

npm run deploy отказывается развёртывать админ-Worker, пока у управляющей базы данных есть неприменённые миграции или когда он не может это определить. Сначала примените их. --skip-migration-check отменяет проверку. Используйте его, только если знаете, что новый код не зависит от неприменённых миграций.

Если миграция не удалась

Миграции применяются по порядку, и каждая отмечается как применённая только после успешного выполнения. При ошибке выполнение останавливается; команда сообщает, что миграция не отмечена как применённая. Следующие за ней миграции не применяются. Устраните причину и снова запустите ту же команду: она повторит неудавшуюся миграцию.
Если миграция остановилась на полпути, повторный запуск выполняет её по одному оператору и пропускает только те операторы, чьи таблица, индекс, триггер или столбец уже существуют, чтобы она могла завершиться. Миграцию, которая содержит блок BEGIN … END, не являющийся триггером, так разделить нельзя. Команда завершается с ошибкой и указывает проблемную миграцию. Приведите схему в порядок вручную, прежде чем повторять запуск.
Не исправляйте неудавшуюся миграцию правкой миграции, которая уже где-то применена. Добавьте новую миграцию, которая её исправляет, запустите migrate:sync и примените снова.
Прежде чем применять рискованную миграцию к развёрнутой базе данных, сделайте экспорт: npx wrangler d1 export <database-name> --remote --output backup.sql из backend/. Cloudflare D1 также сохраняет историю изменений (Time Travel), которая позволяет восстановить базу данных на момент до миграции.
Если npm run deploy отказывает из-за неприменённых миграций, примените их командой npm run migrate:d1, а не обходите проверку.

Стабильная версия ещё не выпущена (pre-MVP)
Коммит исходного кода: e207e63239a627fbd2ae9c414ef7c6eb19fcfe5a (с локальными изменениями)
Дата сборки (UTC): 2026-10-21T09:28:24.214Z
Коммит для обновления: не определён: в рабочей копии есть изменения. Примечания к выпуску