# 機能設計書 181-Mount-DbaDatabase

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Mount-DbaDatabase` コマンドレットの機能設計書である。このコマンドレットは、SQL Serverインスタンスからデタッチされたデータベースファイルを再アタッチする機能を提供する。

### 本機能の処理概要

本機能は、SQL Serverからデタッチされたデータベースファイル（.mdf, .ldf, .ndf）を指定したSQL Serverインスタンスに再アタッチし、データベースを利用可能な状態に復元する。SQL Server Management Objects (SMO) の AttachDatabase メソッドを使用してデータベースファイルの再接続を行う。

**業務上の目的・背景**：データベースの移行作業、サーバー間でのデータベースファイルのコピー移動、災害復旧シナリオにおいて、物理的にディスク上に存在するデータベースファイルをSQL Serverインスタンスに再登録する必要がある。手動でT-SQLコマンドを実行するよりも、PowerShellによる自動化・バッチ処理が可能となり、運用効率が向上する。

**機能の利用シーン**：
- サーバーリプレース時のデータベース移行作業
- バックアップからリストアしたファイルをデタッチ状態でコピーした後のアタッチ
- 開発環境への本番データベースのコピー配置
- 災害復旧時のデータベース再構築

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. データベース所有者の検証と設定（指定がない場合はsaまたはID=1のログインを使用）
3. データベースが既にアタッチ済みかどうかの確認
4. FileStructureが指定されていない場合、バックアップ履歴から自動的にファイル構造を取得
5. SMO AttachDatabaseメソッドによるデータベースのアタッチ処理
6. 処理結果のオブジェクト出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)、バックアップ履歴システム（msdb）

**権限による制御**：データベースのアタッチにはCREATE DATABASE権限またはsysadminサーバーロールが必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | データベース管理 | 補助機能 | データベースのアタッチ |

## 機能種別

CRUD操作（データベースオブジェクトの作成/アタッチ）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | パイプラインから入力可能 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | Windows認証、SQL認証、AD認証をサポート |
| Database | string[] | Yes | アタッチするデータベース名の配列 | 必須パラメータ |
| FileStructure | StringCollection | No | データベースファイルのパスコレクション | 指定なしの場合はバックアップ履歴から自動取得 |
| DatabaseOwner | string | No | データベース所有者のログイン名 | 存在しない場合はsaまたはID=1のログインを使用 |
| AttachOption | string | No | アタッチオプション（None, RebuildLog, EnableBroker, NewBroker, ErrorBrokerConversations） | ValidateSetによる制限、デフォルトはNone |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverインスタンス指定（直接指定またはパイプライン入力）
- ファイルシステム上のデータベースファイル
- バックアップ履歴（FileStructure未指定時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（computer\instance形式） |
| Database | string | アタッチされたデータベース名 |
| AttachResult | string | アタッチ操作の結果（Success） |
| AttachOption | string | 使用されたアタッチオプション |
| FileStructure | StringCollection | アタッチされたファイルパスのコレクション |

### 出力先

PowerShellパイプライン（PSCustomObjectとして出力）

## 処理フロー

### 処理シーケンス

```
1. SQL Serverインスタンスへの接続
   └─ Connect-DbaInstanceを使用して接続を確立
2. データベース所有者の検証
   └─ 指定されたDatabaseOwnerが存在するか確認
   └─ 存在しない場合はsaまたはID=1のログインをデフォルト設定
3. 各データベースの処理ループ
   └─ データベースが既にアタッチ済みかチェック
4. FileStructureの取得（未指定時）
   └─ Get-DbaDbBackupHistoryでバックアップ履歴を取得
   └─ Read-DbaBackupHeaderでファイルリストを取得
   └─ Test-DbaPathでファイル存在確認
5. ShouldProcess確認
   └─ WhatIfまたはConfirmの処理
6. AttachDatabaseメソッドの実行
   └─ SMO AttachDatabaseでアタッチ処理
7. 結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E[DatabaseOwner検証]
    E --> F{存在する?}
    F -->|No| G[saまたはID=1を設定]
    F -->|Yes| H[各データベースを処理]
    G --> H
    H --> I{既にアタッチ済み?}
    I -->|Yes| J[Stop-Function]
    I -->|No| K{FileStructure指定?}
    K -->|No| L[バックアップ履歴から取得]
    K -->|Yes| M[ShouldProcess確認]
    L --> N{取得成功?}
    N -->|No| O[Stop-Function]
    N -->|Yes| M
    M --> P[AttachDatabase実行]
    P --> Q{成功?}
    Q -->|No| R[Stop-Function]
    Q -->|Yes| S[結果出力]
    S --> T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 重複アタッチ禁止 | 同名のデータベースが既にアタッチされている場合は処理をスキップ | 常時 |
| BR-002 | 所有者デフォルト | DatabaseOwnerが無効な場合、saまたはID=1のログインを使用 | DatabaseOwner未指定または無効時 |
| BR-003 | ファイル自動検出 | FileStructure未指定時はバックアップ履歴から自動取得を試行 | FileStructure未指定時 |
| BR-004 | ファイル存在確認 | アタッチ前にすべてのファイルの存在を確認 | FileStructure自動取得時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| バックアップ履歴取得 | msdb.dbo.backupset等 | SELECT | 最新のフルバックアップ情報を取得 |
| データベースアタッチ | sys.databases等 | INSERT/UPDATE | システムカタログにデータベースを登録 |

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

#### msdb（バックアップ履歴）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | backup_set_id, database_name, type等 | type='D'（フルバックアップ）の最新レコード | Get-DbaDbBackupHistory経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 接続情報の確認、ネットワーク確認 |
| - | データベース重複 | 同名データベースが既にアタッチ済み | 別名でアタッチまたは既存DBを削除 |
| - | ファイル構造取得失敗 | バックアップ履歴からファイル情報を取得できない | FileStructureパラメータを明示的に指定 |
| - | ファイル不存在 | 指定されたファイルが存在しない | ファイルパスの確認、ファイルの配置 |
| - | アタッチ失敗 | SMO AttachDatabaseメソッドの失敗 | ファイル破損確認、権限確認 |

### リトライ仕様

リトライ処理は実装されていない。エラー発生時はStop-Functionで処理を中断。

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

SMO AttachDatabaseメソッドは内部的にトランザクションを管理。PowerShellスクリプトレベルでの明示的なトランザクション制御なし。

## パフォーマンス要件

データベースファイルサイズおよびディスクI/O性能に依存。大規模データベースのアタッチには時間を要する場合がある。

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

- CREATE DATABASE権限またはsysadminロールが必要
- SqlCredentialによる安全な資格情報管理
- データベースファイルへのSQL Serverサービスアカウントのアクセス権が必要

## 備考

- Linux上のSQL Serverでも動作可能（パス区切り文字に注意）
- WhatIfスイッチによる事前確認が可能
- Confirmスイッチによる確認プロンプトが可能

---

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

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

### 推奨読解順序

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

パラメータと出力オブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Mount-DbaDatabase.ps1 | `public/Mount-DbaDatabase.ps1` | 96-109行目のparamブロックで入力パラメータの定義を確認 |

**読解のコツ**: DbaInstanceParameter型はdbatools独自の型で、サーバー名やインスタンス名を柔軟に受け入れる。StringCollectionはファイルパスのコレクションを格納。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Mount-DbaDatabase.ps1 | `public/Mount-DbaDatabase.ps1` | 110行目のprocessブロックが処理の開始点 |

**主要処理フロー**:
1. **111-116行目**: SQL Serverインスタンスへの接続処理（Connect-DbaInstance）
2. **118-124行目**: DatabaseOwnerの検証とデフォルト設定
3. **126-130行目**: データベースの重複チェック
4. **132-152行目**: FileStructureの自動取得処理
5. **155-171行目**: ShouldProcessとAttachDatabase実行

#### Step 3: バックアップ履歴取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Mount-DbaDatabase.ps1 | `public/Mount-DbaDatabase.ps1` | 132-152行目のFileStructure自動取得ロジック |

**主要処理フロー**:
- **133行目**: Get-DbaDbBackupHistoryで最新のフルバックアップを取得
- **141行目**: Read-DbaBackupHeaderでファイルリストを取得
- **145-148行目**: Test-DbaPathで各ファイルの存在確認

#### Step 4: アタッチ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Mount-DbaDatabase.ps1 | `public/Mount-DbaDatabase.ps1` | 155-171行目のアタッチ実行処理 |

**主要処理フロー**:
- **157行目**: SMO AttachDatabaseメソッドの呼び出し
- **159-167行目**: 成功時の結果オブジェクト生成

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

```
Mount-DbaDatabase
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続の確立
    │
    ├─ Get-DbaDbBackupHistory (FileStructure未指定時)
    │      └─ msdbからバックアップ履歴を取得
    │
    ├─ Read-DbaBackupHeader (FileStructure未指定時)
    │      └─ バックアップファイルからファイルリストを取得
    │
    ├─ Test-DbaPath (FileStructure未指定時)
    │      └─ ファイル存在確認
    │
    └─ $server.AttachDatabase()
           └─ SMOによるデータベースアタッチ
```

### データフロー図

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

SqlInstance ────────▶ Connect-DbaInstance ────────▶ $server (SMO Server)
Database ─────────────────────────────────────────▶ データベース名
FileStructure ─────▶ (または自動取得) ────────────▶ ファイルパス一覧
                              │
                              ▼
                     AttachDatabase()
                              │
                              ▼
                     PSCustomObject ─────────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Mount-DbaDatabase.ps1 | `public/Mount-DbaDatabase.ps1` | ソース | メイン機能の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続機能 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
| Read-DbaBackupHeader.ps1 | `public/Read-DbaBackupHeader.ps1` | ソース | バックアップヘッダー読み取り |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス存在確認 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
