データベースとマイグレーション

インストールとセットアップ

手順の前に、始める前に と ターミナルの基本 をお読みください。これらの手順では、VS Code で完全な supastack モノリポジトリを開いたことが前提となっています。そのルート package.json はリポジトリのルートをマークします。 pnpm コマンドでは、ワークスペース パッケージはアプリまたは共有コード フォルダーです。この製品では、ワークスペースはチームのデータ コンテナであり、セキュリティ境界です。 corepack pnpm --filter ... コマンドがルートから実行されている間にモノリポジトリから 1 つのパッケージを選択します。同期されたモバイル フォルダーまたはデスクトップ フォルダーのみを開いた場合、そのフォルダーには Web バックエンド、Docker セットアップ、またはルート スクリプトが含まれていません。このモノリポジトリまたはアクセス可能なホスト サーバーからバックエンドを実行し、プラットフォーム フォルダー独自のスクリプトを使用します。環境変数は、ローカルの .env ファイルまたはホスティング ダッシュボードに保存される名前付き設定です。変更後に関連するアプリを再起動し、NEXT_PUBLIC_ および EXPO_PUBLIC_ 値にサーバー シークレットが含まれないようにします。

1. Docker Desktopをインストールして起動します。

2. .env.example を、移行ツールの場合はルートの .env にコピーし、Next.js の場合は apps/web/.env.local にコピーします (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 コンテナーは正常であり、Web アプリは移行されたデータベースを使用します。この最初の実行を運用環境で決して指定しないでください。

サーバー環境でターゲット Postgres データベース向けに DATABASE_URL を設定します。統合受け入れには別の使い捨てデータベースを使います。テストマイグレーションを本番データベースに向けないでください。

データベースワークスペースはスキーマ定義と永続化ヘルパーをエクスポートします。テーブルやカラムを導入する前に 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

コピーするコマンド

コメントに従って、コマンドがどのフォルダーで実行されるかを確認します。 2 つのターミナルにラベルが付いている場合は、2 つのターミナル ウィンドウを開き、2 番目のコマンドを使用している間、最初のコマンドを実行し続けます。

# 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:merge が接続できない場合は、ルート .env を確認してください。データベースを変更する場合は、両方のファイルを更新してください。再試行する前に、最初に失敗した移行ステートメントを読んでください。本番環境に対して決して同じことを繰り返さないでください。

分離されたデータベースにマイグレーションを適用し、その上でデータベースゲート付きテストを実行します。認証情報の欠落は、成功した永続化の主張ではなく明示的にスキップされたゲートを生み出すべきです。マイグレーションが失敗したら、再試行前にどのステートメントが失敗したかと現在のスキーマを検査します。