# 機能設計書 354-Invoke-DbaDbLogShipping

## 概要

本ドキュメントは、SQL Serverログシッピング構成を自動的にセットアップする `Invoke-DbaDbLogShipping` コマンドの機能設計書である。

### 本機能の処理概要

本機能は、プライマリとセカンダリのSQL Serverインスタンス間でログシッピングを構成する。バックアップ、コピー、リストアの各ジョブとスケジュールを自動作成し、Azure Blob Storageへのバックアップもサポートする。

**業務上の目的・背景**：ログシッピングはSQL Server Standardエディションでも利用可能な災害復旧ソリューションである。しかし、手動での構成は複数のストアドプロシージャの実行、ジョブの作成、スケジュールの設定など複雑な手順を要する。本機能により、これらの構成作業を自動化し、設定ミスを防止できる。Azure Blob Storage対応により、クラウドベースのDRソリューションも構築可能。

**機能の利用シーン**：
- 新規ログシッピング環境の構築
- 既存環境へのログシッピング追加
- オンプレミスからAzureへのDR構成
- 複数データベースへの一括ログシッピング設定

**主要な処理内容**：
1. ソース/デスティネーションサーバーへの接続と検証
2. 共有パスまたはAzure Blob Storage URLの検証
3. データベースのリカバリモデル確認（FULL必須）
4. 初期バックアップの実行またはフルバックアップからの復元
5. プライマリ側：バックアップジョブとスケジュールの作成
6. セカンダリ側：コピージョブ、リストアジョブとスケジュールの作成
7. 監視サーバーの設定

**関連システム・外部連携**：SQL Server Agent、msdbログシッピングストアドプロシージャ、Azure Blob Storage（オプション）

**権限による制御**：sysadmin権限が必要。ファイル共有への読み書き権限、Azure資格情報（Azure使用時）が必要。

## 関連画面

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

## 機能種別

システム構成 / ログシッピング設定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SourceSqlInstance | DbaInstanceParameter | Yes | プライマリSQL Serverインスタンス | - |
| DestinationSqlInstance | DbaInstanceParameter[] | Yes | セカンダリSQL Serverインスタンス | - |
| SourceSqlCredential | PSCredential | No | ソース認証情報 | - |
| DestinationSqlCredential | PSCredential | No | デスティネーション認証情報 | - |
| Database | Object[] | Yes | 対象データベース名 | FULLリカバリモデル |
| SharedPath | String | No | バックアップ共有パス（UNC形式） | \\\server\share 形式 |
| AzureBaseUrl | String | No | Azure Blob Storage URL | https形式 |
| LocalPath | String | No | ローカルバックアップパス | - |
| BackupJob | String | No | バックアップジョブ名プレフィックス | デフォルト: LSBackup_ |
| BackupRetention | Int | No | バックアップ保持期間（分） | デフォルト: 4320 (72時間) |
| BackupThreshold | Int | No | バックアップ閾値（分） | デフォルト: 60 |
| CopyDestinationFolder | String | No | コピー先フォルダ | - |
| CopyJob | String | No | コピージョブ名プレフィックス | - |
| CopyRetention | Int | No | コピー保持期間（分） | デフォルト: 4320 |
| RestoreJob | String | No | リストアジョブ名プレフィックス | - |
| RestoreDelay | Int | No | リストア遅延（分） | デフォルト: 0 |
| RestoreRetention | Int | No | リストア保持期間（分） | デフォルト: 4320 |
| RestoreThreshold | Int | No | リストア閾値（分） | デフォルト: 45 |
| Standby | Switch | No | スタンバイモード（読み取り可能） | - |
| NoRecovery | Switch | No | NORECOVERYモード | - |
| GenerateFullBackup | Switch | No | フルバックアップを生成 | - |
| UseExistingFullBackup | Switch | No | 既存フルバックアップを使用 | - |
| NoInitialization | Switch | No | 初期化スキップ | - |
| CompressBackup | Switch | No | バックアップ圧縮有効化 | - |
| SecondaryDatabasePrefix | String | No | セカンダリDB名プレフィックス | - |
| SecondaryDatabaseSuffix | String | No | セカンダリDB名サフィックス | - |
| Force | Switch | No | 確認スキップ、デフォルト適用 | - |
| EnableException | Switch | No | 例外制御 | - |

### 入力データソース

- SQL Server構成情報
- msdb.dbo.sp_add_log_shipping_* ストアドプロシージャ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| PrimaryInstance | String | プライマリインスタンス名 |
| SecondaryInstance | String | セカンダリインスタンス名 |
| PrimaryDatabase | String | プライマリデータベース名 |
| SecondaryDatabase | String | セカンダリデータベース名 |
| Result | String | セットアップ結果（Success / Failed） |
| Comment | String | 追加情報またはエラー詳細 |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   ├─ SharedPath または AzureBaseUrl のいずれかが必須
   ├─ パス形式の検証（UNC / Azure URL）
   └─ スケジュールパラメータの検証

2. ソースサーバー接続
   └─ Connect-DbaInstance

3. バックアップ圧縮設定確認
   └─ SQL Server 2008以上で使用可能

4. データベースループ開始
   └─ 各データベースに対して以下を実行

5. リカバリモデル確認
   └─ FULL でない場合はエラー

6. セカンダリデータベース名決定
   └─ Prefix + DBName + Suffix

7. バックアップパス設定
   ├─ LocalPath / SharedPath の構成
   └─ Azure使用時はURL構成

8. セカンダリ初期化
   ├─ GenerateFullBackup: 新規フルバックアップ + リストア
   ├─ UseExistingFullBackup: 既存バックアップ使用
   └─ NoInitialization: 初期化スキップ

9. プライマリ構成
   ├─ sp_add_log_shipping_primary_database
   └─ バックアップジョブ・スケジュール作成

10. セカンダリ構成
    ├─ sp_add_log_shipping_secondary_primary
    ├─ sp_add_log_shipping_secondary_database
    └─ コピー/リストアジョブ・スケジュール作成

11. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SharedPath or AzureBaseUrl?}
    B -->|None| C[エラー: パス必須]
    B -->|OK| D[ソースサーバー接続]
    D --> E[パラメータ検証]
    E --> F[データベースループ開始]
    F --> G{リカバリモデル = FULL?}
    G -->|No| H[エラー: FULL必須]
    G -->|Yes| I[セカンダリDB名決定]
    I --> J{初期化方法?}
    J -->|GenerateFullBackup| K[フルバックアップ生成・リストア]
    J -->|UseExistingFullBackup| L[既存バックアップ使用]
    J -->|NoInitialization| M[初期化スキップ]
    K --> N[プライマリ構成]
    L --> N
    M --> N
    N --> O[sp_add_log_shipping_primary_database]
    O --> P[バックアップジョブ・スケジュール作成]
    P --> Q[セカンダリ構成]
    Q --> R[sp_add_log_shipping_secondary_primary]
    R --> S[sp_add_log_shipping_secondary_database]
    S --> T[コピー/リストアジョブ作成]
    T --> U[結果出力]
    U --> V{次のDB?}
    V -->|Yes| F
    V -->|No| W[終了]
    C --> W
    H --> V
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パス必須 | SharedPath または AzureBaseUrl のいずれかが必須 | 常時 |
| BR-002 | FULLリカバリ必須 | 対象DBはFULLリカバリモデルである必要 | 常時 |
| BR-003 | Azure最小バージョン | Azure Blob使用時はSQL 2012以上必須 | AzureBaseUrl指定時 |
| BR-004 | 同一インスタンス制限 | ソースとデスティネーションが同一の場合、サフィックス必須 | 同一インスタンス時 |

### 計算ロジック

- デフォルトスケジュール: 毎日15分間隔で実行

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プライマリ構成 | msdb.dbo.log_shipping_primary_databases | INSERT | プライマリDB登録 |
| セカンダリ構成 | msdb.dbo.log_shipping_secondary | INSERT | セカンダリ構成登録 |
| ジョブ作成 | msdb.dbo.sysjobs | INSERT | バックアップ/コピー/リストアジョブ |

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

#### msdb ストアドプロシージャ

| 操作 | プロシージャ名 | 用途 |
|-----|----------------|------|
| EXEC | sp_add_log_shipping_primary_database | プライマリDB登録 |
| EXEC | sp_add_log_shipping_primary_secondary | プライマリ-セカンダリ関連付け |
| EXEC | sp_add_log_shipping_secondary_primary | セカンダリからプライマリ参照 |
| EXEC | sp_add_log_shipping_secondary_database | セカンダリDB登録 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NoPath | 検証エラー | SharedPath/AzureBaseUrl両方未指定 | Stop-Function |
| InvalidPath | 検証エラー | パス形式不正 | Stop-Function |
| NotFullRecovery | 検証エラー | リカバリモデルがFULLでない | Stop-Function、次のDBへ |
| AzureVersion | 検証エラー | SQL 2012未満でAzure使用 | Stop-Function |
| SameInstance | 検証エラー | 同一インスタンスでサフィックスなし | Stop-Function |

### リトライ仕様

リトライ処理なし。

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

各ストアドプロシージャ呼び出しは個別トランザクション。部分的な失敗時は手動クリーンアップが必要。

## パフォーマンス要件

- 初期フルバックアップのサイズに依存
- 大規模DBでは GenerateFullBackup に長時間を要する可能性

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

- sysadmin権限が必要
- ファイル共有への適切なアクセス権限設定
- Azure資格情報の事前作成（Azure使用時）

## 備考

- 50以上のパラメータを持つ複雑なコマンド
- スケジュールパラメータの多くはデフォルト値が適用される

---

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

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

### 推奨読解順序

#### Step 1: パラメータ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbLogShipping.ps1 | `public/Invoke-DbaDbLogShipping.ps1` | paramブロック（470-580行目）で50以上のパラメータを確認 |

**読解のコツ**: パラメータは Backup/Copy/Restore の各グループに分類される。Schedule関連パラメータはValidateSetに注意。

#### Step 2: 検証ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbLogShipping.ps1 | `public/Invoke-DbaDbLogShipping.ps1` | beginブロック（582-955行目）で事前検証とデフォルト値設定 |

**主要処理フロー**:
1. **603-655行目**: SharedPath/AzureBaseUrl排他チェックとURL検証
2. **657-669行目**: バックアップ圧縮設定
3. **672-691行目**: Standby/NoRecovery設定
4. **693-805行目**: 各種デフォルト値設定

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbLogShipping.ps1 | `public/Invoke-DbaDbLogShipping.ps1` | processブロック（957行目以降）でメイン処理 |

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

```
Invoke-DbaDbLogShipping
    │
    ├─ Connect-DbaInstance (Source)
    │
    ├─ Connect-DbaInstance (Destination)
    │
    ├─ Test-DbaPath (SharedPath検証)
    │
    ├─ Get-DbaSpConfigure (圧縮設定取得)
    │
    ├─ Backup-DbaDatabase (GenerateFullBackup時)
    │
    ├─ Restore-DbaDatabase (初期リストア)
    │
    ├─ sp_add_log_shipping_primary_database
    │
    ├─ New-DbaAgentSchedule (バックアップスケジュール)
    │
    ├─ sp_add_log_shipping_secondary_primary
    │
    ├─ sp_add_log_shipping_secondary_database
    │
    └─ New-DbaAgentSchedule (コピー/リストアスケジュール)
```

### データフロー図

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

SourceSqlInstance ───▶ Connect-DbaInstance
DestinationSqlInstance      │
Database                    ▼
SharedPath/AzureUrl ───▶ パス検証
                            │
                            ▼
                      DB毎のループ処理
                            │
                  ┌─────────┴─────────┐
                  ▼                   ▼
            プライマリ構成      セカンダリ構成
                  │                   │
                  ▼                   ▼
            バックアップジョブ  コピー/リストアジョブ
                  │                   │
                  └─────────┬─────────┘
                            ▼
                      PSCustomObject ───▶ 結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbLogShipping.ps1 | `public/Invoke-DbaDbLogShipping.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | バックアップ実行 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | リストア実行 |
| New-DbaAgentSchedule.ps1 | `public/New-DbaAgentSchedule.ps1` | ソース | スケジュール作成 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス検証 |
