# バッチ設計書 1-run-migrations

## 概要

本ドキュメントは、Actual Budget同期サーバーのデータベースマイグレーション実行スクリプト「run-migrations」の設計仕様を記載したものです。

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

このバッチは、同期サーバー（sync-server）のデータベーススキーマを管理し、スキーマの変更を適用または取り消すためのマイグレーション処理を実行します。

**業務上の目的・背景**：データベーススキーマの変更をバージョン管理し、本番環境・開発環境・テスト環境間でスキーマの一貫性を保つために必要なバッチです。新機能追加や既存機能の変更に伴うテーブル構造の変更を、安全かつ再現可能な方法で適用できます。マイグレーションの履歴が管理されることで、どの環境がどのスキーマバージョンにあるかを追跡できます。

**バッチの実行タイミング**：手動実行が基本です。サーバーのバージョンアップ時、新機能デプロイ時、または開発環境でのスキーマ変更適用時に実行します。通常はビルド後に`yarn db:migrate`コマンドとして実行されます。

**主要な処理内容**：
1. コマンドライン引数からマイグレーション方向（up/down）を取得
2. `migrate`ライブラリを使用してマイグレーション定義を読み込み
3. データディレクトリ内の`.migrate`ファイルで状態を管理
4. `migrations`ディレクトリ内の全マイグレーションファイルを順次実行
5. 実行完了後に「Migrations: DONE」メッセージを出力

**前後の処理との関連**：本バッチはサーバー起動前に実行される前提処理です。マイグレーション完了後にサーバーアプリケーションが起動されます。ビルド処理（`yarn build`）が先行して実行される必要があります。

**影響範囲**：account.sqliteデータベースのスキーマ、server-filesディレクトリ内のマイグレーション状態ファイル（.migrate）

## バッチ種別

データ連携 / スキーマ管理

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 随時（バージョンアップ時） |
| 実行時刻 | 任意 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | 手動 |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| ビルド完了 | `yarn build`によりTypeScriptがコンパイル済みであること |
| Node.js環境 | Node.js 22以上がインストールされていること |
| データディレクトリ | `ACTUAL_DATA_DIR`で指定されたディレクトリが存在すること |

### 実行可否判定

マイグレーションライブラリが自動的に、未適用のマイグレーションが存在するかをチェックし、存在する場合のみ実行します。すでに適用済みのマイグレーションはスキップされます。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| direction | string | No | up | マイグレーション方向（up: 適用、down: ロールバック） |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| migrations/*.js | JSファイル | マイグレーション定義ファイル群 |
| .migrate | 状態ファイル | マイグレーション適用状態を記録 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| account.sqlite | SQLite DB | スキーマ変更が適用されるデータベース |
| .migrate / .migrate-test | 状態ファイル | マイグレーション状態記録 |
| 標準出力 | テキスト | 実行結果メッセージ |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| ファイル名 | .migrate（本番）/ .migrate-test（テスト） |
| 出力先 | ${dataDir}/ |
| 文字コード | UTF-8 |
| 区切り文字 | 該当なし（バイナリ形式） |

## 処理フロー

### 処理シーケンス

```
1. 引数解析
   └─ process.argv[2]からdirectionを取得（デフォルト: 'up'）
2. マイグレーション設定読み込み
   └─ migrate.load()でmigrationsディレクトリとstateStoreを指定
3. マイグレーション実行
   └─ set[direction]()で指定方向のマイグレーションを実行
4. 完了通知
   └─ 「Migrations: DONE」をコンソール出力
```

### フローチャート

```mermaid
flowchart TD
    A[バッチ開始] --> B[引数から方向取得]
    B --> C{direction指定あり?}
    C -->|あり| D[指定値を使用]
    C -->|なし| E[デフォルト'up'を使用]
    D --> F[migrate.load実行]
    E --> F
    F --> G{読み込みエラー?}
    G -->|あり| H[例外スロー]
    G -->|なし| I[set.up/down実行]
    I --> J{実行エラー?}
    J -->|あり| H
    J -->|なし| K[完了メッセージ出力]
    K --> L[バッチ終了]
    H --> M[エラー終了 exit 1]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 1694360479680 | auth, sessions, files, users, user_access | CREATE TABLE | アカウントDB作成 |
| 1694362247011 | secrets | CREATE TABLE | シークレットテーブル作成 |
| 1702667624000 | secrets | UPDATE | Nordigenシークレット名変更 |
| 1718889148000 | auth | ALTER | OpenID対応カラム追加 |
| 1719409568000 | users, user_access | CREATE/ALTER | マルチユーザー対応 |
| 1763873568237 | server_prefs | CREATE TABLE | サーバー設定テーブル作成 |

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

#### auth
| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE | method, display_name, extra_data, active | 初期値なし | 認証方式管理 |

#### sessions
| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE | token, expires_at, user_id, auth_method | 初期値なし | セッション管理 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| 1 | 実行時エラー | マイグレーション処理失敗 | エラーメッセージを確認し、データベース状態を確認 |

### リトライ仕様

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

### 障害時対応

マイグレーション失敗時は以下の手順で対応します：
1. エラーメッセージを確認し、失敗したマイグレーションを特定
2. データベースの状態を確認（.migrateファイル）
3. 必要に応じて`yarn db:downgrade`でロールバック
4. 問題を修正後、再度`yarn db:migrate`を実行

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

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

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | マイグレーションファイル数（通常1〜10件程度） |
| 目標処理時間 | 数秒〜数十秒 |
| メモリ使用量上限 | 特に制限なし |

## 排他制御

同時実行不可。複数のマイグレーションプロセスが同時に実行されると、データベースの整合性が損なわれる可能性があります。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| 開始ログ | バッチ開始時 | マイグレーション方向と開始メッセージ |
| 進捗ログ | 各マイグレーション実行時 | マイグレーションファイル名 |
| 終了ログ | バッチ終了時 | 「Migrations: DONE」 |
| エラーログ | エラー発生時 | 「Migration failed:」+ エラー詳細 |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| 終了コード | 0以外 | 実行者（手動実行のため） |

## 備考

- 実行コマンド: `yarn db:migrate`（up）/ `yarn db:downgrade`（down）
- テスト環境用: `yarn db:test-migrate` / `yarn db:test-downgrade`
- マイグレーションファイルは`packages/sync-server/migrations/`ディレクトリに配置
- ファイル名は`{timestamp}-{description}.js`形式
