# 機能設計書 353-Invoke-DbaDbLogShipRecovery

## 概要

本ドキュメントは、ログシッピングセカンダリデータベースをオンライン状態に復旧する `Invoke-DbaDbLogShipRecovery` コマンドの機能設計書である。

### 本機能の処理概要

本機能は、ログシッピング構成のセカンダリデータベースを、スタンバイまたは復元中状態から通常の運用可能状態に復旧する。災害復旧シナリオやプライマリ/セカンダリのロール切り替え時に使用する。

**業務上の目的・背景**：ログシッピングはSQL Serverの災害復旧ソリューションとして広く採用されている。プライマリサーバー障害時、または計画的なサーバー移行時に、セカンダリデータベースを迅速にオンライン化する必要がある。本機能により、コピージョブとリストアジョブの完了確認、ジョブの無効化、RESTORE WITH RECOVERYの実行という複雑な復旧ワークフローを自動化できる。

**機能の利用シーン**：
- プライマリサーバー障害時の災害復旧
- 計画的なプライマリ/セカンダリのロール切り替え
- ログシッピング構成の解除とセカンダリの本番昇格
- データセンター移行時のフェイルオーバー

**主要な処理内容**：
1. SQL Server Agentサービスの稼働状態確認
2. ログシッピング構成情報（コピージョブ、リストアジョブ）の取得
3. コピージョブの実行・完了待機・無効化
4. リストアジョブの実行・完了待機・無効化
5. RESTORE DATABASE WITH RECOVERY の実行（-NoRecovery指定時はスキップ）

**関連システム・外部連携**：SQL Server Agent、msdbログシッピングテーブル、Start-DbaAgentJob、Set-DbaAgentJob、Get-DbaAgentJobコマンドを使用。

**権限による制御**：sysadmin権限が必要。SQLAgentジョブの操作権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データベース操作 / 災害復旧

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| Database | String[] | No | 復旧対象データベース名 | -Forceなしの場合は必須 |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効な資格情報 |
| NoRecovery | Switch | No | WITH RECOVERYをスキップ | - |
| InputObject | Database[] | No | パイプライン入力用データベースオブジェクト | - |
| Force | Switch | No | 全データベース対象、確認スキップ | - |
| Delay | Int | No | ジョブ完了確認ポーリング間隔（秒） | デフォルト5秒 |
| EnableException | Switch | No | 例外制御 | - |
| WhatIf | Switch | No | 実行シミュレーション | - |
| Confirm | Switch | No | 実行確認 | - |

### 入力データソース

- msdb.dbo.log_shipping_secondary
- msdb.dbo.log_shipping_secondary_databases
- msdb.dbo.sysjobs

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverが稼働するコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Database | String | 復旧対象データベース名 |
| RecoverResult | String | 復旧結果（Success / Failed） |
| Comment | String | 追加情報またはエラー詳細 |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 事前検証
   ├─ -Force または -Database の指定チェック
   └─ 対象データベースの取得（Get-DbaDatabase）

2. SQL Server Agentサービス確認
   └─ SQLAgentプロセス数の確認クエリ実行

3. ログシッピング構成情報取得
   └─ msdbからcopy_job_id, restore_job_idを取得

4. データベース状態確認
   └─ Standby, Restoring, Normal,Standby のいずれかを確認

5. コピージョブ処理
   ├─ Start-DbaAgentJob でコピージョブ開始
   ├─ ジョブ完了まで Delay 間隔でポーリング
   ├─ 失敗時はエラー記録
   └─ Set-DbaAgentJob -Disabled でジョブ無効化

6. リストアジョブ処理
   ├─ Start-DbaAgentJob でリストアジョブ開始
   ├─ ジョブ完了まで Delay 間隔でポーリング
   ├─ 失敗時はエラー記録
   └─ Set-DbaAgentJob -Disabled でジョブ無効化

7. データベース復旧（-NoRecovery でない場合）
   └─ RESTORE DATABASE [$db] WITH RECOVERY 実行

8. 結果出力
   └─ PSCustomObject で結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{-Force or -Database?}
    B -->|No| C[エラー: データベース指定必須]
    B -->|Yes| D[Get-DbaDatabase]
    D --> E[データベースループ開始]
    E --> F{Agent稼働中?}
    F -->|No| G[エラー: Agent停止]
    F -->|Yes| H[ログシッピング情報取得]
    H --> I{構成あり?}
    I -->|No| J[スキップ: 未構成]
    I -->|Yes| K{DB状態OK?}
    K -->|No| L[スキップ: 状態不正]
    K -->|Yes| M[コピージョブ開始]
    M --> N[ジョブ完了待機]
    N --> O{成功?}
    O -->|No| P[エラー記録]
    O -->|Yes| Q[コピージョブ無効化]
    Q --> R[リストアジョブ開始]
    R --> S[ジョブ完了待機]
    S --> T{成功?}
    T -->|No| U[エラー記録]
    T -->|Yes| V[リストアジョブ無効化]
    V --> W{-NoRecovery?}
    W -->|Yes| X[スキップ: RESTORE省略]
    W -->|No| Y[RESTORE WITH RECOVERY]
    X --> Z[結果出力]
    Y --> Z
    P --> Z
    U --> Z
    Z --> AA{次のDB?}
    AA -->|Yes| E
    AA -->|No| AB[終了]
    C --> AB
    G --> AB
    J --> AA
    L --> AA
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | データベース指定必須 | -Forceなしの場合、-Databaseの指定が必須 | -Force未指定時 |
| BR-002 | Agent稼働必須 | SQL Server Agentが稼働している必要あり | 常時 |
| BR-003 | 状態チェック | Standby, Restoring, Normal,Standbyのいずれかが必要 | 常時 |
| BR-004 | ジョブ無効化 | コピー/リストアジョブは処理後に無効化 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 構成取得 | msdb.dbo.log_shipping_secondary | SELECT | セカンダリ構成取得 |
| 構成取得 | msdb.dbo.log_shipping_secondary_databases | SELECT | セカンダリDB情報取得 |
| 構成取得 | msdb.dbo.sysjobs | SELECT | ジョブ情報取得 |
| 復旧 | 対象DB | ALTER DATABASE | RESTORE WITH RECOVERY |

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

#### ログシッピング構成テーブル

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | primary_server, primary_database, secondary_database, backup_source_directory, copy_job_id, restore_job_id | secondary_database = $db.Name | ジョブ名も取得 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NoDatabase | 検証エラー | -Database未指定かつ-Force未指定 | Stop-Function |
| AgentStopped | 前提条件エラー | SQL Agent停止 | Stop-Function |
| CopyJobFailed | ジョブエラー | コピージョブ失敗 | エラー記録、処理継続 |
| RestoreJobFailed | ジョブエラー | リストアジョブ失敗 | エラー記録、処理継続 |
| RecoveryFailed | 復旧エラー | RESTORE WITH RECOVERY失敗 | Stop-Function |

### リトライ仕様

リトライ処理なし。ジョブ完了までのポーリングは実装。

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

RESTORE DATABASE WITH RECOVERYは暗黙的トランザクション。失敗時はデータベース状態維持。

## パフォーマンス要件

- ジョブ完了ポーリング間隔はDelayパラメータで調整可能（デフォルト5秒）

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

- sysadmin権限が必要
- SQLAgentジョブ操作権限が必要

## 備考

- SupportsShouldProcess対応（WhatIf/Confirm）
- 複数データベースの一括復旧対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbLogShipRecovery.ps1 | `public/Invoke-DbaDbLogShipRecovery.ps1` | T-SQLクエリ（157-164行目）でmsdb構造確認 |

**読解のコツ**: ログシッピング関連テーブルの結合関係を理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbLogShipRecovery.ps1 | `public/Invoke-DbaDbLogShipRecovery.ps1` | 関数全体の処理フロー |

**主要処理フロー**:
1. **110-122行目**: パラメータ定義
2. **128-155行目**: Agent稼働確認
3. **157-174行目**: ログシッピング構成取得
4. **195-234行目**: コピージョブ処理
5. **252-287行目**: リストアジョブ処理
6. **303-316行目**: RESTORE WITH RECOVERY実行

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

```
Invoke-DbaDbLogShipRecovery
    │
    ├─ Get-DbaDatabase
    │
    ├─ $server.Query() ─ Agent稼働確認
    │
    ├─ $server.Query() ─ ログシッピング構成取得
    │
    ├─ Start-DbaAgentJob (コピージョブ)
    │      └─ Get-DbaAgentJob (完了確認ポーリング)
    │
    ├─ Set-DbaAgentJob -Disabled (コピージョブ無効化)
    │
    ├─ Start-DbaAgentJob (リストアジョブ)
    │      └─ Get-DbaAgentJob (完了確認ポーリング)
    │
    ├─ Set-DbaAgentJob -Disabled (リストアジョブ無効化)
    │
    └─ $server.Query() ─ RESTORE WITH RECOVERY
```

### データフロー図

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

SqlInstance ───▶ Get-DbaDatabase
Database            │
                    ▼
              Agent稼働確認
                    │
                    ▼
              ログシッピング構成取得
                    │
                    ▼
              コピージョブ実行・待機・無効化
                    │
                    ▼
              リストアジョブ実行・待機・無効化
                    │
                    ▼
              RESTORE WITH RECOVERY ───▶ PSCustomObject
                                          (RecoverResult)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbLogShipRecovery.ps1 | `public/Invoke-DbaDbLogShipRecovery.ps1` | ソース | メイン関数 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Start-DbaAgentJob.ps1 | `public/Start-DbaAgentJob.ps1` | ソース | ジョブ開始 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ状態取得 |
| Set-DbaAgentJob.ps1 | `public/Set-DbaAgentJob.ps1` | ソース | ジョブ設定変更 |
