# 画面設計書 53-ログシッピング

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるログシッピング（Log Shipping）管理機能の設計仕様を記載したものです。SQL Serverのログシッピング構成の設定・削除・リカバリ・ステータス確認機能を提供します。

### 本画面の処理概要

本機能は、SQL Serverのログシッピングを包括的に管理するためのPowerShellコマンド群を提供します。ログシッピングは、プライマリデータベースからセカンダリデータベースへトランザクションログを定期的にバックアップ・コピー・リストアすることで、災害復旧（DR）およびレポーティング環境を実現する高可用性ソリューションです。

**業務上の目的・背景**：ログシッピングは、SQL Server Enterprise Editionを必要とせず、Standard Editionでも利用可能な災害復旧ソリューションです。多くの組織でDRサイトの構築、読み取り専用レポーティングサーバーの提供、データベースのオフサイトバックアップなどに活用されています。本機能は、ログシッピングの複雑な設定プロセスを自動化し、一貫性のある構成管理を実現します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `Invoke-DbaDbLogShipping` - ログシッピングの設定
- `Remove-DbaDbLogShipping` - ログシッピングの削除
- `Invoke-DbaDbLogShipRecovery` - ログシッピングリカバリの実行
- `Get-DbaDbLogShipError` - ログシッピングエラーの取得
- `Test-DbaDbLogShipStatus` - ログシッピングステータスのテスト

**主要な操作・処理内容**：
1. プライマリ・セカンダリインスタンス間のログシッピング構成設定
2. バックアップ・コピー・リストアジョブとスケジュールの作成
3. セカンダリデータベースの初期化（フルバックアップから）
4. Azure Blob Storageを使用したログシッピング構成
5. ログシッピング構成の削除とクリーンアップ
6. ログシッピングエラーの監視とステータス確認

**画面遷移**：本機能はCLIコマンドであり、他のdbatools機能との連携が可能です。データベースオブジェクトをパイプライン入力として受け取ることができます。

**権限による表示制御**：ログシッピングの設定にはプライマリおよびセカンダリの両インスタンスでsysadmin権限が必要です。また、バックアップ・コピーパスへの適切なファイルシステム権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 354 | Invoke-DbaDbLogShipping | 主機能 | ログシッピングの設定 |
| 355 | Remove-DbaDbLogShipping | 主機能 | ログシッピングの削除 |
| 353 | Invoke-DbaDbLogShipRecovery | 補助機能 | ログシッピングリカバリの実行 |
| 352 | Get-DbaDbLogShipError | 補助機能 | ログシッピングエラーの取得 |
| 356 | Test-DbaDbLogShipStatus | 補助機能 | ログシッピングステータスのテスト |

## 画面種別

構成設定・実行（CLI）

## URL/ルーティング

PowerShellコマンドとして以下のコマンドレット名でアクセス:
- `Invoke-DbaDbLogShipping`
- `Remove-DbaDbLogShipping`
- `Invoke-DbaDbLogShipRecovery`
- `Get-DbaDbLogShipError`
- `Test-DbaDbLogShipStatus`

## 入出力項目

### Invoke-DbaDbLogShipping 主要パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SourceSqlInstance | Yes | DbaInstanceParameter | ソースSQL Serverインスタンス |
| DestinationSqlInstance | Yes | DbaInstanceParameter[] | 宛先SQL Serverインスタンス |
| Database | Yes | object[] | 対象データベース |
| SharedPath | No* | string | 共有バックアップパス（UNC形式） |
| AzureBaseUrl | No* | string | Azure Blob Storage URL |
| BackupScheduleFrequencyType | No | string | バックアップスケジュール頻度タイプ |
| CopyScheduleFrequencyType | No | string | コピースケジュール頻度タイプ |
| RestoreScheduleFrequencyType | No | string | リストアスケジュール頻度タイプ |
| GenerateFullBackup | No | switch | フルバックアップを生成 |
| NoRecovery | No | switch | NORECOVERYモード |
| Standby | No | switch | STANDBYモード |
| Force | No | switch | 確認をバイパス |

*SharedPathとAzureBaseUrlは相互排他

## 表示項目

### Invoke-DbaDbLogShipping 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| PrimaryInstance | string | プライマリインスタンス名 |
| SecondaryInstance | string | セカンダリインスタンス名 |
| PrimaryDatabase | string | プライマリデータベース名 |
| SecondaryDatabase | string | セカンダリデータベース名 |
| Result | string | 設定結果（Success/Failed） |
| Comment | string | 追加情報 |

## イベント仕様

### 1-ログシッピング設定

1. ソースおよび宛先インスタンスへの接続確立
2. データベースのリカバリモデル確認（FULLが必要）
3. バックアップ共有パスまたはAzure URLの検証
4. フルバックアップの生成（GenerateFullBackup指定時）
5. セカンダリデータベースの初期化（NORECOVERY/STANDBYモード）
6. プライマリサーバーでのバックアップジョブとスケジュール作成
7. セカンダリサーバーでのコピージョブとスケジュール作成（ファイルベースの場合）
8. セカンダリサーバーでのリストアジョブとスケジュール作成
9. 監視サーバーの設定（オプション）
10. 結果オブジェクトの出力

### 2-ログシッピング削除

1. プライマリおよびセカンダリのログシッピング構成を識別
2. 関連するSQL Agentジョブの削除
3. msdbからのログシッピングメタデータの削除
4. セカンダリデータベースの状態変更（オプション）

### 3-ログシッピングリカバリ

1. セカンダリデータベースの状態確認
2. 残存トランザクションログのリストア
3. データベースのリカバリ実行
4. プライマリとしての昇格

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbLogShipping | msdb.dbo.log_shipping_primary_* | INSERT | プライマリ設定の登録 |
| Invoke-DbaDbLogShipping | msdb.dbo.log_shipping_secondary_* | INSERT | セカンダリ設定の登録 |
| Invoke-DbaDbLogShipping | msdb.dbo.sysjobs | INSERT | バックアップ/コピー/リストアジョブの作成 |
| Invoke-DbaDbLogShipping | msdb.dbo.sysjobschedules | INSERT | ジョブスケジュールの作成 |
| Remove-DbaDbLogShipping | msdb.dbo.log_shipping_* | DELETE | ログシッピング設定の削除 |
| Remove-DbaDbLogShipping | msdb.dbo.sysjobs | DELETE | 関連ジョブの削除 |

### テーブル別更新項目詳細

#### msdb.dbo.log_shipping_primary_databases（プライマリ設定）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | primary_database | データベース名 | プライマリDB名 |
| INSERT | backup_directory | SharedPath/AzureBaseUrl | バックアップ先 |
| INSERT | backup_retention_period | BackupRetention | 保持期間（分） |
| INSERT | backup_threshold | BackupThreshold | アラート閾値 |

#### msdb.dbo.log_shipping_secondary_databases（セカンダリ設定）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | secondary_database | データベース名 | セカンダリDB名 |
| INSERT | restore_delay | RestoreDelay | リストア遅延（分） |
| INSERT | restore_mode | 0/1 | NORECOVERY/STANDBY |
| INSERT | restore_threshold | RestoreThreshold | アラート閾値 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Database recovery model is not FULL | リカバリモデルがFULL以外 |
| MSG-002 | エラー | SharedPath or AzureBaseUrl must be specified | 両方未指定時 |
| MSG-003 | 警告 | Copy destination not specified | コピー先未指定時 |
| MSG-004 | 情報 | Log shipping configured successfully | 設定成功時 |
| MSG-005 | エラー | Failed to create backup job | ジョブ作成失敗時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理停止、エラーメッセージ出力 |
| リカバリモデル不正 | FULLリカバリモデルが必要である旨のエラー |
| パス権限不足 | 必要なファイルシステム権限の説明を含むエラー |
| ジョブ作成失敗 | 詳細エラー情報を含むFailure結果 |
| Azure認証エラー | AzureCredentialの設定確認を促すエラー |

## 備考

- ログシッピングはSQL Server 2000以降で利用可能
- Azure Blob Storageを使用する場合はSQL Server 2012以降が必要
- Standbyモードはレポーティング用途に適しているが、リストア中はユーザー切断が発生
- 同一インスタンス内でのログシッピングにはSecondaryDatabaseSuffixの指定が必要
- バックアップジョブのデフォルト間隔は15分

---

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

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

### 推奨読解順序

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

ログシッピング関連のシステムテーブルとオブジェクト構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | msdb.dbo.log_shipping_primary_databases | システムテーブル | プライマリ設定の構造 |
| 1-2 | msdb.dbo.log_shipping_secondary_databases | システムテーブル | セカンダリ設定の構造 |
| 1-3 | msdb.dbo.log_shipping_monitor_* | システムテーブル | 監視設定の構造 |

**読解のコツ**: ログシッピングはプライマリ、セカンダリ、モニターの3種類のサーバーロールで構成されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbLogShipping.ps1 | `public/Invoke-DbaDbLogShipping.ps1` | ログシッピング設定のメインロジック |

**主要処理フロー (Invoke-DbaDbLogShipping)**:
1. **行468-499**: パラメータ定義（ソース、宛先、スケジュール設定など）
2. **行1-300**: ヘルプドキュメント（パラメータ説明、例）
3. **処理部**: データベースごとのログシッピング設定実行

#### Step 3: ジョブ作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAgentJob | `public/New-DbaAgentJob.ps1` | ジョブ作成処理 |
| 3-2 | New-DbaAgentSchedule | `public/New-DbaAgentSchedule.ps1` | スケジュール作成処理 |

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

```
Invoke-DbaDbLogShipping
    |
    +-- Connect-DbaInstance (Source)
    |
    +-- Connect-DbaInstance (Destination)
    |
    +-- パラメータ検証
    |       +-- SharedPath/AzureBaseUrl確認
    |       +-- リカバリモデル確認
    |
    +-- セカンダリDB初期化
    |       +-- Backup-DbaDatabase (GenerateFullBackup時)
    |       +-- Restore-DbaDatabase
    |
    +-- プライマリ設定
    |       +-- sp_add_log_shipping_primary_database
    |       +-- New-DbaAgentJob (Backup)
    |       +-- New-DbaAgentSchedule
    |
    +-- セカンダリ設定
    |       +-- sp_add_log_shipping_secondary_primary
    |       +-- sp_add_log_shipping_secondary_database
    |       +-- New-DbaAgentJob (Copy/Restore)
    |       +-- New-DbaAgentSchedule
    |
    +-- 結果出力
            +-- PSCustomObject
```

### データフロー図

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

SourceSqlInstance   --->  Connect-DbaInstance (Primary)
                                |
DestinationSqlInstance -->  Connect-DbaInstance (Secondary)
                                |
                                v
Database            --->  リカバリモデル確認
                                |
SharedPath/         --->  パス検証
AzureBaseUrl              |
                          v
GenerateFullBackup  --->  Backup-DbaDatabase
                                |
                                v
                         Restore-DbaDatabase (NORECOVERY/STANDBY)
                                |
                                v
BackupSchedule*     --->  sp_add_log_shipping_primary_database
                                |
                                v
CopySchedule*       --->  sp_add_log_shipping_secondary_*
RestoreSchedule*          |
                          v
                         New-DbaAgentJob/Schedule
                                |
                                v
                         結果オブジェクト  ---->  PSCustomObject
                                                 (PrimaryInstance,
                                                  SecondaryInstance,
                                                  Result)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbLogShipping.ps1 | `public/Invoke-DbaDbLogShipping.ps1` | ソース | ログシッピング設定コマンド |
| Remove-DbaDbLogShipping.ps1 | `public/Remove-DbaDbLogShipping.ps1` | ソース | ログシッピング削除コマンド |
| Invoke-DbaDbLogShipRecovery.ps1 | `public/Invoke-DbaDbLogShipRecovery.ps1` | ソース | リカバリ実行コマンド |
| Get-DbaDbLogShipError.ps1 | `public/Get-DbaDbLogShipError.ps1` | ソース | エラー取得コマンド |
| Test-DbaDbLogShipStatus.ps1 | `public/Test-DbaDbLogShipStatus.ps1` | ソース | ステータステストコマンド |
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | バックアップ実行 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | リストア実行 |
| New-DbaAgentJob.ps1 | `public/New-DbaAgentJob.ps1` | ソース | ジョブ作成 |
| New-DbaAgentSchedule.ps1 | `public/New-DbaAgentSchedule.ps1` | ソース | スケジュール作成 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
