# バッチ設計書 36-db:schema:dump

## 概要

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

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

`db:schema:dump` タスクは、現在のデータベーススキーマをファイルに出力するためのRakeタスクである。Ruby形式（db/schema.rb）またはSQL形式（db/structure.sql）でスキーマを出力し、バージョン管理やスキーマの共有に使用する。

**業務上の目的・背景**：データベーススキーマをコードとして管理し、チーム間でのスキーマ共有、環境間の一貫性確保、新規環境の高速セットアップを実現するために使用される。マイグレーション実行後に自動的に呼び出されることが多く、常に最新のスキーマ状態をファイルに反映する。

**バッチの実行タイミング**：以下のタイミングで実行される：
- `db:migrate` 実行後（`ActiveRecord.dump_schema_after_migration` が true の場合）
- 開発者による手動実行
- CI/CDパイプラインでのスキーマ検証

**主要な処理内容**：
1. 現在の環境のすべてのデータベース設定をループ処理
2. 各データベースに対して、設定されたフォーマット（ruby/sql）でスキーマをダンプ
3. Ruby形式の場合：`SchemaDumper.dump` を使用してschema.rbを生成
4. SQL形式の場合：データベースアダプタの `structure_dump` を使用してstructure.sqlを生成
5. schema_migrationsテーブルの内容もダンプに含める

**前後の処理との関連**：
- 関連タスク：`db:migrate`（マイグレーション後に自動実行される場合あり）
- 関連タスク：`db:schema:load`（ダンプされたスキーマをロード）
- 設定依存：`config.active_record.schema_format` でフォーマットを制御

**影響範囲**：db/schema.rb または db/structure.sql ファイルが生成・更新される。データベース自体への変更は行わない。

## バッチ種別

スキーマ管理 / ファイル生成

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（マイグレーション後） |
| 実行時刻 | 任意 |
| 実行曜日 | 任意 |
| 実行日 | 任意 |
| トリガー | 手動/自動（db:migrate後） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| データベース存在 | 対象データベースが作成済みであること |
| データベース接続可能 | 接続情報が正しく設定されていること |
| db_config.schema_dump | スキーマダンプが有効（false でない）であること |

### 実行可否判定

- `db_config.schema_dump` が false の場合はスキップ
- schema_dump_path が nil の場合はスキップ
- 同一のスキーマパスが既に処理済みの場合はスキップ（重複防止）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| RAILS_ENV | 環境変数 | No | development | 対象環境を指定 |
| SCHEMA | 環境変数 | No | 設定による | スキーマファイルのパスを指定 |
| SCHEMA_FORMAT | 環境変数 | No | config設定値 | フォーマット（ruby/sql）を指定 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| データベース | DB | 現在のスキーマ情報を取得 |
| config/database.yml | YAML | データベース接続設定 |
| schema_migrations テーブル | DB | マイグレーションバージョン情報 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| db/schema.rb | Ruby | Ruby形式のスキーマ定義 |
| db/structure.sql | SQL | SQL形式のスキーマ定義 |
| 標準出力 | テキスト | 処理結果メッセージ（VERBOSEモード） |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | schema.rb（Ruby形式）/ structure.sql（SQL形式） |
| 出力先 | db/ ディレクトリ |
| 文字コード | UTF-8 |
| 上書き動作 | 既存ファイルを上書き |

## 処理フロー

### 処理シーケンス

```
1. load_config
   └─ Railsアプリケーションとデータベース設定をロード
2. dump_all メソッド実行
   └─ 各データベース設定をループ処理
   └─ 重複スキーマパスをスキップ
3. dump_schema メソッド実行（各DB）
   └─ 3.1 schema_dump が false ならスキップ
   └─ 3.2 schema_dump_path を取得
   └─ 3.3 db_dir を作成（存在しない場合）
   └─ 3.4 フォーマットに応じてダンプ
4. Ruby形式（:ruby）の場合
   └─ SchemaDumper.dump でスキーマを生成
   └─ schema.rb にUTF-8で書き込み
5. SQL形式（:sql）の場合
   └─ structure_dump でDDLを生成
   └─ schema_migrationsの内容を追記
   └─ structure.sql に書き込み
```

### フローチャート

```mermaid
flowchart TD
    A[db:schema:dump 開始] --> B[設定ロード]
    B --> C[各DB設定をループ]
    C --> D{schema_dump有効?}
    D -->|No| E[スキップ]
    D -->|Yes| F{スキーマパス取得}
    F -->|nil| E
    F -->|取得成功| G{重複チェック}
    G -->|既に処理済み| E
    G -->|未処理| H[db_dir 作成]
    H --> I{フォーマット判定}
    I -->|ruby| J[SchemaDumper.dump]
    J --> K[schema.rb 書き込み]
    I -->|sql| L[structure_dump]
    L --> M[schema_migrations追記]
    M --> N[structure.sql 書き込み]
    K --> O[次のDB設定へ]
    N --> O
    E --> O
    O --> P{全DB処理完了?}
    P -->|No| C
    P -->|Yes| Q[db:schema:dump 完了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| スキーマ取得 | 全テーブル | SELECT (メタデータ) | テーブル定義情報を取得 |
| バージョン取得 | schema_migrations | SELECT | マイグレーションバージョンを取得 |

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

データベースへの書き込み操作は行わない（読み取りのみ）。

#### schema_migrations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | version | 全バージョン取得 | structure.sqlに追記用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | データベース接続失敗 | database.yml設定を確認 |
| - | IOError | ファイル書き込み失敗 | db/ディレクトリの権限を確認 |
| - | ArgumentError | 不正なフォーマット指定 | ruby または sql を指定 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | - |
| リトライ対象エラー | - |

### 障害時対応

1. エラーメッセージを確認し、原因を特定
2. データベース接続を確認
3. db/ディレクトリの書き込み権限を確認
4. 必要に応じてSCHEMA_FORMAT環境変数を確認

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | なし（読み取り専用） |
| コミットタイミング | - |
| ロールバック条件 | - |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | テーブル数に依存 |
| 目標処理時間 | 通常数秒以内 |
| メモリ使用量上限 | スキーマサイズに依存 |

## 排他制御

- 同時実行可能（読み取り専用のため）
- ファイル書き込み時の競合に注意
- マイグレーション実行中の同時ダンプは避けること

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | タスク開始時 | （VERBOSEモードで出力） |
| 進捗ログ | 処理中 | ダンプ対象情報 |
| 終了ログ | タスク終了時 | （VERBOSEモードで出力） |
| エラーログ | エラー発生時 | エラー詳細メッセージ |

## 監視・アラート

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

## 備考

- `structure_dump_flags` でアダプタ固有のフラグを指定可能（mysqldump/pg_dump用）
- Ruby形式（schema.rb）はデータベース非依存だが、一部機能（トリガー、関数等）は表現できない
- SQL形式（structure.sql）はデータベース固有だが、全ての機能を表現可能
- マルチデータベース構成では、各DBごとに別のスキーマファイルを生成可能
- `db:migrate` 後の自動ダンプは `ActiveRecord.dump_schema_after_migration` で制御
- タスクは `reenable` されるため、同一実行内で複数回呼び出し可能
- SCHEMA環境変数でカスタムパスを指定した場合、その値が優先される
