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

## 概要

本ドキュメントは、Railsフレームワークが提供するデータベースセットアップ用Rakeタスク `db:setup` の設計仕様について記載する。

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

`db:setup` タスクは、データベースの作成、スキーマのロード、およびシードデータの投入を一括で実行するためのRakeタスクである。新規プロジェクトのセットアップや、クリーンな状態からデータベースを構築する際に使用する。

**業務上の目的・背景**：新しい開発環境のセットアップ、CI/CDパイプラインでのデータベース初期化、新規チームメンバーの環境構築時など、データベースを初期状態から構築する必要がある場合に使用する。マイグレーションを実行せずスキーマファイルから直接ロードするため、高速な初期化が可能である。

**バッチの実行タイミング**：開発者が手動で実行する随時タスクである。主に以下のタイミングで使用される：
- 新規プロジェクトのクローン後の初期セットアップ
- CI/CDパイプラインでのテスト環境構築
- 開発環境の新規セットアップ時

**主要な処理内容**：
1. `db:create` タスクを実行し、データベースを作成する
2. `environment` タスクを実行し、Railsアプリケーション環境をロードする
3. `db:schema:load` タスクを実行し、スキーマファイルをデータベースにロードする
4. `db:seed` タスクを実行し、シードデータを投入する

**前後の処理との関連**：
- 前提：データベース設定（config/database.yml）が正しく構成されていること
- 前提：スキーマファイル（db/schema.rb または db/structure.sql）が存在すること
- 関連タスク：`db:reset`（既存DBを削除してからsetupを実行）
- 関連タスク：`db:prepare`（DBの存在有無に応じてsetupまたはmigrateを実行）

**影響範囲**：新規データベースが作成され、スキーマに基づいたテーブル構造が構築される。シードデータが投入され、アプリケーションの初期状態が整う。既存データベースが存在する場合、db:createは警告を出力するが処理は続行される。

## バッチ種別

データベース管理 / 環境セットアップ

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時 |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動（bin/rails db:setup） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース設定 | config/database.yml が正しく設定されていること |
| スキーマファイル | db/schema.rb または db/structure.sql が存在すること |
| データベースサーバー | 対象のデータベースサーバーが稼働していること |
| シードファイル | db/seeds.rb が存在すること（任意） |

### 実行可否判定

- スキーマファイルが存在しない場合はエラーとなる
- データベースが既に存在する場合、db:createは警告を出力するが処理は続行される
- 環境保護チェックは `db:schema:load` で実行される

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| RAILS_ENV | 環境変数 | No | development | 対象環境を指定 |
| VERBOSE | 環境変数 | No | true | 処理の詳細出力を制御 |
| SCHEMA | 環境変数 | No | db/schema.rb | スキーマファイルのパス |
| SCHEMA_FORMAT | 環境変数 | No | config設定値 | スキーマフォーマット（ruby/sql） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| config/database.yml | YAML | データベース接続設定 |
| db/schema.rb | Ruby | スキーマ定義ファイル（Ruby形式） |
| db/structure.sql | SQL | スキーマ定義ファイル（SQL形式） |
| db/seeds.rb | Ruby | シードデータ定義ファイル |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| データベース | DB | スキーマに基づいて構築されたデータベース |
| 標準出力 | テキスト | 処理結果メッセージ |
| 標準エラー出力 | テキスト | 警告・エラーメッセージ |

### 出力ファイル仕様

ファイル出力は行わない。データベースの構築のみを実行する。

## 処理フロー

### 処理シーケンス

```
1. db:create タスク実行
   └─ 設定に基づきデータベースを作成
2. environment タスク実行
   └─ Railsアプリケーション環境をロード
3. db:schema:load タスク実行
   └─ スキーマファイルをデータベースにロード
   └─ テーブル構造を構築
   └─ ar_internal_metadata テーブルを作成・更新
4. db:seed タスク実行
   └─ pending_migrations チェック
   └─ db/seeds.rb を実行
   └─ シードデータを投入
```

### フローチャート

```mermaid
flowchart TD
    A[db:setup 開始] --> B[db:create]
    B --> C{DB存在チェック}
    C -->|存在しない| D[データベース作成]
    C -->|存在する| E[警告出力して続行]
    D --> F[environment ロード]
    E --> F
    F --> G[db:schema:load]
    G --> H{スキーマファイル存在}
    H -->|存在| I[スキーマロード実行]
    H -->|存在しない| J[エラー終了]
    I --> K[db:seed]
    K --> L{pending migrations チェック}
    L -->|なし| M[seeds.rb 実行]
    L -->|あり| N[エラー: 未適用マイグレーション]
    M --> O[db:setup 完了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| db:create | - | CREATE DATABASE | 新規データベースを作成 |
| db:schema:load | 全テーブル | CREATE TABLE | スキーマに基づきテーブル作成 |
| db:schema:load | ar_internal_metadata | INSERT | メタデータを記録 |
| db:schema:load | schema_migrations | INSERT | マイグレーションバージョンを記録 |
| db:seed | シード対象テーブル | INSERT/UPDATE | 初期データを投入 |

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

#### ar_internal_metadata

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | key | 'environment' | 環境名を記録 |
| INSERT | value | Rails.env | 現在の環境 |
| INSERT | key | 'schema_sha1' | スキーマのハッシュ値 |
| INSERT | created_at, updated_at | 現在時刻 | タイムスタンプ |

#### schema_migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | version | スキーマファイル内のバージョン | 全マイグレーションバージョン |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DatabaseAlreadyExists | データベースが既に存在 | 警告のみ、処理続行 |
| - | NoDatabaseError | データベースサーバーに接続不可 | 接続設定を確認 |
| - | スキーマファイルエラー | スキーマファイルが存在しない | db:migrateを実行してスキーマを生成 |
| - | PendingMigrationError | 未適用マイグレーションが存在 | db:migrateを実行 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし（手動タスクのため） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーメッセージを確認し、原因を特定
2. データベースサーバーの稼働状態を確認
3. database.yml の設定を確認
4. スキーマファイルの存在を確認
5. 必要に応じて `db:migrate` を実行してスキーマを生成

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | db:schema:load: ファイル全体、db:seed: seeds.rb内の実装に依存 |
| コミットタイミング | 各タスク完了時 |
| ロールバック条件 | エラー発生時 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | スキーマ内のテーブル数、シードデータ量に依存 |
| 目標処理時間 | スキーマサイズ・シードデータ量に依存（通常数秒〜数分） |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

- 同時実行は非推奨
- データベース作成時は排他ロックが自動的に取得される
- スキーマロード中は他の接続からのアクセスを避けること

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | 各サブタスク開始時 | タスク名 |
| 進捗ログ | 処理中 | "Created database 'xxx'" 等 |
| 警告ログ | DB存在時 | "Database 'xxx' already exists" |
| 終了ログ | 各サブタスク終了時 | 完了メッセージ |
| エラーログ | エラー発生時 | エラー詳細メッセージ |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 処理時間 | プロジェクトに応じて設定 | 開発者 |
| エラー件数 | 1件以上 | 開発者 |

## 備考

- `db:setup` はスキーマファイルを直接ロードするため、マイグレーションを順次実行するよりも高速
- 既存データベースがある場合は `db:reset` を使用すること（drop + setup）
- マルチデータベース構成の場合、`db:setup:データベース名` で個別に実行可能
- development環境で実行すると、DATABASE_URLが設定されていない限り、test環境のデータベースも同時にセットアップされる
- seeds.rb の実行前に pending_migrations チェックが行われ、未適用マイグレーションがある場合はエラーとなる
