# 機能設計書 4-データベース接続管理

## 概要

本ドキュメントは、Laravel Frameworkのデータベース接続管理機能について、その設計思想、処理フロー、および実装詳細を記述したものである。DatabaseManagerを中心とした複数データベース接続の管理機能設計を定義する。

### 本機能の処理概要

データベース接続管理機能は、MySQL、PostgreSQL、SQLite、SQL Server、MariaDBなど複数のデータベースシステムへの接続を統一的に管理する機能である。接続の生成、キャッシュ、切断、再接続などのライフサイクル管理を提供する。

**業務上の目的・背景**：現代のアプリケーションは複数のデータベースを利用することがある（読み取り専用レプリカ、テナント別DB、外部サービス連携など）。本機能は、これらの複雑な接続管理を抽象化し、開発者が接続の詳細を意識することなくデータベース操作を行えるようにする。また、接続プーリングや自動再接続により、安定した運用を実現する。

**機能の利用シーン**：
- 複数データベースへの接続切り替え
- 読み取り/書き込み分離（Read/Write Splitting）
- マルチテナントアプリケーション
- テスト時のインメモリSQLite使用
- 動的な接続設定の構築

**主要な処理内容**：
1. 接続インスタンスの生成とキャッシュ
2. 接続設定の解決と検証
3. 読み取り/書き込み接続の分離管理
4. 自動再接続機能
5. 接続の切断とリソース解放
6. カスタムドライバの拡張登録

**関連システム・外部連携**：
- PDO（PHP Data Objects）
- 各データベースドライバ（pdo_mysql、pdo_pgsql等）
- Event Dispatcher（ConnectionEstablishedイベント）
- Transaction Manager（トランザクション管理）

**権限による制御**：データベースレベルの権限は各DBMSの認証・認可機構に依存する。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 直接関連する画面なし（インフラ機能） |

## 機能種別

インフラストラクチャ / 接続管理 / ドライバ管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string\|UnitEnum | No | 接続名 | config定義済み |
| config | array | No | 動的接続設定 | ドライバ必須 |

### 入力データソース

- config/database.php（接続設定）
- 環境変数（DB_*）
- 動的設定（DB::build()）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| connection | Connection | データベース接続インスタンス |

### 出力先

- アプリケーションコード（クエリ実行）
- Event Dispatcher（ConnectionEstablishedイベント）

## 処理フロー

### 処理シーケンス

```
1. 接続リクエスト
   └─ connection($name)で接続名を指定
2. キャッシュ確認
   └─ connections配列から既存接続を検索
3. 接続生成
   └─ ConnectionFactoryで新規接続を生成
4. 接続設定
   └─ PDO設定、イベントディスパッチャ、トランザクションマネージャ設定
5. イベント発火
   └─ ConnectionEstablishedイベントをディスパッチ
6. キャッシュ保存
   └─ connections配列に保存
```

### フローチャート

```mermaid
flowchart TD
    A[connection($name)] --> B{キャッシュあり?}
    B -->|Yes| C[キャッシュから返却]
    B -->|No| D[parseConnectionName()]
    D --> E[makeConnection()]
    E --> F{拡張登録あり?}
    F -->|Yes| G[カスタムリゾルバ呼び出し]
    F -->|No| H[ConnectionFactory::make()]
    G --> I[configure()]
    H --> I
    I --> J[setPdoForType()]
    J --> K[setEventDispatcher()]
    K --> L[setTransactionManager()]
    L --> M[setReconnector()]
    M --> N[dispatchConnectionEstablishedEvent()]
    N --> O[connectionsに保存]
    O --> P[接続返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 遅延接続 | 実際のPDO接続はクエリ実行時まで遅延 | Connector設定による |
| BR-02 | 自動再接続 | 接続が切断された場合は自動で再接続を試行 | setReconnector()設定時 |
| BR-03 | Read/Write分離 | `::read`/`::write`サフィックスで接続タイプを指定 | 接続名に含む場合 |
| BR-04 | デフォルト接続 | 接続名省略時はconfig('database.default')を使用 | connection()引数なし |

### 計算ロジック

- 動的接続名: `dynamic_` + MD5(設定のシリアライズ)

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

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

本機能は接続管理のみで、直接的なCRUD操作は行わない。

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| - | - | - | 接続管理のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | InvalidArgumentException | 未定義の接続名を指定 | config/database.phpを確認 |
| - | RuntimeException | 同名の接続が既に存在（connectUsing） | purge()で既存接続を削除 |
| - | PDOException | データベース接続失敗 | 接続設定を確認 |

### リトライ仕様

reconnect()メソッドで明示的な再接続が可能。自動再接続はreconnectorコールバックで実装。

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

本機能はトランザクション管理機能との連携をサポート。setTransactionManager()でトランザクションマネージャを設定。

## パフォーマンス要件

- 接続はリクエスト内でキャッシュ（同一接続の再取得は高速）
- 遅延接続により不要な接続を回避
- 接続プール未使用（PHP-FPMで十分なケースが多い）

## セキュリティ考慮事項

- 接続情報は環境変数から取得推奨
- パスワードはログ出力時にマスク
- SSL/TLS接続オプションをサポート

## 備考

- extend()でカスタム接続リゾルバを登録可能
- usingConnection()で一時的な接続切り替えが可能
- supportedDrivers()でサポートドライバ一覧取得

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ConnectionResolverInterface.php | `src/Illuminate/Database/ConnectionResolverInterface.php` | 接続リゾルバのインターフェース |
| 1-2 | ConnectionInterface.php | `src/Illuminate/Database/ConnectionInterface.php` | 接続のインターフェース |
| 1-3 | Connection.php | `src/Illuminate/Database/Connection.php` | 接続の基底クラス |

**読解のコツ**: インターフェースで定義されたメソッド（connection, getDefaultConnection等）を先に理解すること。

#### Step 2: DatabaseManagerを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | DatabaseManager.php | `src/Illuminate/Database/DatabaseManager.php` | 接続管理の中心クラス |

**主要処理フロー**:
- **75-85行目**: コンストラクタでapp、factory、reconnector初期化
- **93-109行目**: connection()で接続取得（キャッシュ優先）
- **117-124行目**: build()で動的接続構築
- **147-164行目**: connectUsing()で設定指定接続
- **185-204行目**: makeConnection()で接続インスタンス生成
- **214-226行目**: configuration()で接続設定取得
- **235-256行目**: configure()で接続を準備
- **299-304行目**: purge()で接続削除
- **312-317行目**: disconnect()で切断
- **325-336行目**: reconnect()で再接続
- **403-406行目**: supportedDrivers()でサポートドライバ一覧

#### Step 3: ConnectionFactoryを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | ConnectionFactory.php | `src/Illuminate/Database/Connectors/ConnectionFactory.php` | 接続ファクトリ |

**読解ポイント**:
- make()メソッドで接続インスタンスを生成
- 各ドライバ（MySQL、PostgreSQL等）の接続クラスを選択
- Read/Write接続の設定

#### Step 4: 個別Connectorを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | MySqlConnector.php | `src/Illuminate/Database/Connectors/MySqlConnector.php` | MySQL接続 |
| 4-2 | PostgresConnector.php | `src/Illuminate/Database/Connectors/PostgresConnector.php` | PostgreSQL接続 |
| 4-3 | SQLiteConnector.php | `src/Illuminate/Database/Connectors/SQLiteConnector.php` | SQLite接続 |

### プログラム呼び出し階層図

```
DB Facade / app('db')
    │
    └─ DatabaseManager::connection($name)
           │
           ├─ [キャッシュあり]
           │      └─ connections[$name] 返却
           │
           └─ [キャッシュなし]
                  │
                  ├─ parseConnectionName($name)
                  │      └─ ['database', 'read|write|null']
                  │
                  ├─ makeConnection($database)
                  │      │
                  │      ├─ configuration($name)
                  │      │      └─ config['database.connections.$name']
                  │      │
                  │      ├─ extensions[$name] 存在時
                  │      │      └─ カスタムリゾルバ呼び出し
                  │      │
                  │      └─ factory->make($config, $name)
                  │             └─ ConnectionFactory::make()
                  │                    ├─ createConnector()
                  │                    │      └─ MySqlConnector等
                  │                    └─ createConnection()
                  │                           └─ MySqlConnection等
                  │
                  └─ configure($connection, $type)
                         ├─ setPdoForType()
                         ├─ setEventDispatcher()
                         ├─ setTransactionManager()
                         └─ setReconnector()
```

### データフロー図

```
[入力]                    [処理]                         [出力]

config/database.php ───▶ DatabaseManager ───────────────▶ Connection
                              │
                              ▼
                        ConnectionFactory
                              │
                              ▼
                        Connector (MySQL/Postgres/SQLite)
                              │
                              ▼
                        PDO接続 ─────────────────────────▶ DBMS
                              │
                              ▼
                        ConnectionEstablished Event ────▶ Event Dispatcher
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| DatabaseManager.php | `src/Illuminate/Database/DatabaseManager.php` | ソース | 接続マネージャ |
| DatabaseServiceProvider.php | `src/Illuminate/Database/DatabaseServiceProvider.php` | ソース | サービスプロバイダ |
| Connection.php | `src/Illuminate/Database/Connection.php` | ソース | 接続基底クラス |
| MySqlConnection.php | `src/Illuminate/Database/MySqlConnection.php` | ソース | MySQL接続 |
| PostgresConnection.php | `src/Illuminate/Database/PostgresConnection.php` | ソース | PostgreSQL接続 |
| SQLiteConnection.php | `src/Illuminate/Database/SQLiteConnection.php` | ソース | SQLite接続 |
| SqlServerConnection.php | `src/Illuminate/Database/SqlServerConnection.php` | ソース | SQL Server接続 |
| ConnectionFactory.php | `src/Illuminate/Database/Connectors/ConnectionFactory.php` | ソース | 接続ファクトリ |
| Connector.php | `src/Illuminate/Database/Connectors/Connector.php` | ソース | コネクタ基底クラス |
| MySqlConnector.php | `src/Illuminate/Database/Connectors/MySqlConnector.php` | ソース | MySQLコネクタ |
| PostgresConnector.php | `src/Illuminate/Database/Connectors/PostgresConnector.php` | ソース | PostgreSQLコネクタ |
| SQLiteConnector.php | `src/Illuminate/Database/Connectors/SQLiteConnector.php` | ソース | SQLiteコネクタ |
| ConfigurationUrlParser.php | `src/Illuminate/Support/ConfigurationUrlParser.php` | ソース | 接続URL解析 |
| ConnectionEstablished.php | `src/Illuminate/Database/Events/ConnectionEstablished.php` | ソース | 接続確立イベント |
