База данных и миграции

Настройка и конфигурация

Перед любым действием прочтите Перед началом работы и Основные сведения о терминале. В этих инструкциях предполагается, что вы открыли полный монорепозиторий supastack в VS Code; его корень package.json отмечает корень репозитория. В командах pnpm пакет рабочей области представляет собой папку приложения или общего кода; В продукте рабочее пространство — это контейнер данных и граница безопасности команды. corepack pnpm --filter ... выбирает один пакет из монорепозитория, пока команды выполняются из его корня. Если вы открыли только синхронизированную папку мобильного устройства или рабочего стола, она не содержит веб-серверной части, настройки Docker или корневых сценариев: запустите серверную часть из этого монорепозитория или доступного размещенного сервера и используйте собственные сценарии папки платформы. Переменная среды — это именованный параметр, хранящийся в локальном файле .env или на панели управления хостингом; перезапустите соответствующее приложение после его изменения и не допускайте попадания секретов сервера в значения NEXT_PUBLIC_ и EXPO_PUBLIC_.

1. Установите и запустите Docker Desktop.

2. Скопируйте .env.example в .env в корне для инструментов миграции и в apps/web/.env.local для Next.js (PowerShell: Copy-Item .env.example .env; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash: cp .env.example .env; cp.env.example apps/web/.env.local). Оставьте DATABASE_URL одинаковым в обоих файлах; пример уже соответствует локальной базе данных Docker.

3. Из корня репозитория запустите docker compose up -d postgres и docker compose ps; подождите, пока postgres не сообщит об исправности.

4. Запустите corepack pnpm --filter @supastack/db db:migrate из корня, чтобы применить миграции, уже поставляемые с комплектом. Только после редактирования packages/db/src/schema.ts запустите db:generate, проверьте сгенерированный SQL, затем запустите db:migrate. Ожидается: локальный контейнер Postgres работоспособен, и веб-приложение использует перенесенную базу данных. Никогда не направляйте этот первый запуск на производство.

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

Воркспейс базы экспортирует определения схемы и помощники персистентности. Просмотрите packages/db/src/schema.ts и каталог миграций до введения таблицы или колонки.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

# Optional Compose / Supabase settings in .env:
# POSTGRES_PASSWORD=supastack
# SUPABASE_ACCESS_TOKEN=
# DATABASE_POOLER=transaction

Команды для копирования

Следуйте комментариям, чтобы узнать, в какой папке запускается команда. Если помечены два терминала, откройте два окна терминала и продолжайте выполнять первую команду, пока используете вторую.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

Рабочий процесс внедрения

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

Включайте workspaceId в каждую запись пользователя и несите эту область в чтения и записи. Используйте неизменную историю цен моделей для учёта AI вместо перезаписи цен, используемых существующими записями использования.

Проверка и устранение неполадок

Если Docker сообщает, что не может подключиться к своему движку, запустите Docker Desktop и подождите, пока он завершит загрузку. Если postgres неработоспособен, запустите docker compose logs postgres из корня и исправьте эту ошибку перед миграцией. Если Web сообщает, что DATABASE_URL отсутствует, проверьте apps/web/.env.local; если db:migrate не может подключиться, проверьте корневой .env. Если вы меняете базы данных, обновите оба файла. Прежде чем повторять попытку, прочитайте первое неудачное заявление о миграции; никогда не повторяйте это против производства.

Применяйте миграции к изолированной базе и запускайте там тесты, зависящие от базы. Отсутствующие креденшелы должны давать явно пропущенный шлюз, а не утверждение о прохождении персистентности. Если миграция падает, инспектируйте, какой оператор упал, и текущую схему до повтора.