# バッチ設計書 11-db:setup

## 概要

本ドキュメントは、Medusaフレームワークにおけるデータベースセットアップ用CLIコマンド「db:setup」の設計仕様を定義する。

### 本バッチの処理概要

db:setupコマンドは、Medusaアプリケーションのデータベース環境を一括でセットアップするためのCLIコマンドである。データベースの作成からマイグレーション実行までを一連の流れで実行し、開発者が新しい環境を迅速に構築できるようにする。

**業務上の目的・背景**：新規開発環境の構築やCI/CD環境でのデータベース初期化において、複数のコマンドを個別に実行する手間を省き、単一コマンドでデータベースの完全なセットアップを実現する必要がある。これにより、開発者の生産性向上とセットアップ手順の標準化を図る。

**バッチの実行タイミング**：新規環境構築時、CI/CDパイプライン実行時、または開発者が手動で実行する任意のタイミング。主に初期セットアップ時に一度だけ実行される。

**主要な処理内容**：
1. Medusaコンテナの初期化（DB接続なし）
2. dbCreateによるデータベースの作成（存在チェック含む）
3. Medusaコンテナの再初期化（DB接続あり）
4. migrateによるマイグレーション実行（リンク同期、スクリプト実行を含む）

**前後の処理との関連**：db:createとdb:migrateの両方の機能を統合したコマンドであり、個別に実行する場合はそれぞれのコマンドを使用する。後続処理としてmedusa startによるサーバー起動が想定される。

**影響範囲**：PostgreSQLデータベースの作成、.envファイルのDB_NAME更新、全モジュールのマイグレーションテーブル、リンクテーブルの同期。

## バッチ種別

データベース初期化 / マイグレーション実行

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（初期セットアップ時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動（CLIコマンド） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| PostgreSQLサーバー稼働 | 接続先のPostgreSQLサーバーが起動している必要がある |
| DATABASE_URL設定 | .envファイルにDATABASE_URLが設定されていること |
| Node.js環境 | Node.jsがインストールされていること |
| medusa-config.js存在 | プロジェクトルートにmedusa-config.jsが存在すること |

### 実行可否判定

1. DATABASE_URLが.envファイルに定義されているか確認
2. PostgreSQLサーバーへの接続が可能か確認
3. 接続に失敗した場合はpostgresデータベースへの接続を試行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| directory | string | No | process.cwd() | プロジェクトディレクトリパス |
| interactive | boolean | No | true | 対話モードの有効/無効 |
| db | string | No | undefined | 作成するデータベース名 |
| skipLinks | boolean | No | false | リンク同期をスキップするか |
| skipScripts | boolean | No | false | マイグレーションスクリプトをスキップするか |
| executeAllLinks | boolean | No | false | 全リンクを強制実行するか |
| executeSafeLinks | boolean | No | false | 安全なリンクのみ実行するか |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| .env | 環境変数ファイル | DATABASE_URL、DB_NAMEの読み込み |
| medusa-config.js | JavaScript設定ファイル | モジュール設定の読み込み |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| PostgreSQLデータベース | DB | 新規作成されたデータベース |
| .envファイル | テキストファイル | DB_NAME環境変数の更新 |
| マイグレーションテーブル | DB | 各モジュールのマイグレーション履歴 |
| 標準出力 | コンソール | 実行ログ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | .env |
| 出力先 | プロジェクトルート |
| 文字コード | UTF-8 |
| 更新内容 | DB_NAME={データベース名} |

## 処理フロー

### 処理シーケンス

```
1. コンテナ初期化（DB接続なし）
   └─ initializeContainerでMedusaコンテナを初期化（skipDbConnection: true）
2. ロガー取得
   └─ ContainerRegistrationKeys.LOGGERを解決
3. データベース作成
   └─ dbCreate関数を呼び出し
      ├─ .envファイルからDATABASE_URLを取得
      ├─ DB名を決定（引数 > DB_NAME > slugify(directory)）
      ├─ PostgreSQLクライアント接続
      ├─ データベース存在チェック
      ├─ 存在しない場合は新規作成
      └─ .envファイルにDB_NAMEを設定
4. コンテナ再初期化（DB接続あり）
   └─ initializeContainerでMedusaコンテナを再初期化
5. マイグレーション実行
   └─ migrate関数を呼び出し
      ├─ データベース存在確認
      ├─ モジュールマイグレーション実行
      ├─ リンク同期（skipLinksがfalseの場合）
      └─ マイグレーションスクリプト実行（skipScriptsがfalseの場合）
6. プロセス終了
   └─ 成功時はexit(0)、失敗時はexit(1)
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[コンテナ初期化 DB接続なし]
    B --> C[ロガー取得]
    C --> D[dbCreate呼び出し]
    D --> E{DB作成成功?}
    E -->|No| F[exit 1]
    E -->|Yes| G[コンテナ再初期化 DB接続あり]
    G --> H[migrate呼び出し]
    H --> I{マイグレーション成功?}
    I -->|No| F
    I -->|Yes| J[exit 0]
    F --> K[バッチ終了]
    J --> K
```

## データベース操作仕様

### 操作別データベース影響一覧

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DB作成 | - | CREATE DATABASE | 新規データベースの作成 |
| マイグレーション | mikro_orm_migrations | INSERT | マイグレーション履歴の記録 |
| マイグレーション | 各モジュールテーブル | CREATE/ALTER | テーブル構造の変更 |
| リンク同期 | link_* | CREATE/ALTER | モジュール間リンクテーブルの同期 |

### テーブル別操作詳細

#### mikro_orm_migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | マイグレーションファイル名 | 実行済みマイグレーションを記録 |
| INSERT | executed_at | 実行日時 | マイグレーション実行時刻 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | PostgreSQLサーバーに接続できない | DATABASE_URLの確認、サーバー起動確認 |
| - | 設定エラー | DATABASE_URLが未設定 | .envファイルにDATABASE_URLを設定 |
| ExitPromptError | ユーザー中断 | 対話モードでユーザーが中断 | 正常終了として処理 |
| DB_ERROR | マイグレーションエラー | マイグレーション実行中のエラー | エラーメッセージを確認し原因を特定 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（単発実行） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーログを確認し、失敗箇所を特定
2. データベース接続の問題の場合はDATABASE_URLを確認
3. マイグレーションエラーの場合はdb:rollbackで巻き戻し後、再実行
4. 部分的に成功している場合は個別コマンド（db:create、db:migrate）で続行

## トランザクション仕様

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | マイグレーション単位 |
| コミットタイミング | 各マイグレーション完了時 |
| ロールバック条件 | マイグレーション実行中のエラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | モジュール数依存（30+モジュール） |
| 目標処理時間 | 環境依存（通常1-5分） |
| メモリ使用量上限 | Node.jsデフォルト制限 |

## 排他制御

データベース作成時およびマイグレーション実行時は他のプロセスからの同時実行を想定していない。CI/CD環境では排他制御を外部で実装すること。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | - | 出力なし（サブコマンドで出力） |
| 進捗ログ | DB作成時 | Connection established / Created database / Updated .env |
| 進捗ログ | マイグレーション時 | MODULE: {moduleName} / Migrating / Migrated |
| 終了ログ | マイグレーション完了時 | Migrations completed |
| エラーログ | エラー発生時 | エラーメッセージおよびスタックトレース |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | 環境依存 | 標準出力 |
| エラー件数 | 1件以上 | 標準エラー出力 |

## 備考

- db:setupはdb:createとdb:migrateを統合したコンビニエンスコマンドである
- 対話モード（interactive: true）では、DB名の入力を求めるプロンプトが表示される
- 非対話モードでは、DB_NAME環境変数または「medusa-{slugify(directory)}」がデフォルト値として使用される
- PostgreSQLのデフォルトデータベースに接続できない場合は、postgresデータベースへの接続を試行する
