# 画面設計書 213-MaintenanceSolution

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける「Maintenance Solution」機能（Install-DbaMaintenanceSolution、Update-DbaMaintenanceSolution、Get-DbaMaintenanceSolutionLog）の画面設計書です。Ola Hallengren氏が開発した業界標準のSQL Serverメンテナンスソリューションをインストール・更新・監視する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：SQL Server管理者は、バックアップ、データベース整合性チェック、インデックス最適化などの定期メンテナンスタスクを自動化する必要があります。Ola Hallengren's Maintenance Solutionは、世界中の数千のSQL Server環境で使用されている業界標準のメンテナンスフレームワークです。手動でのT-SQLスクリプト作成の手間を削減し、ベストプラクティスに基づいたメンテナンスを実現します。

**画面へのアクセス方法**：PowerShellコンソールから `Install-DbaMaintenanceSolution`、`Update-DbaMaintenanceSolution`、または `Get-DbaMaintenanceSolutionLog` コマンドを実行します。

**主要な操作・処理内容**：
1. **Install-DbaMaintenanceSolution**:
   - GitHubから最新のMaintenance Solutionをダウンロード
   - DatabaseBackup、DatabaseIntegrityCheck、IndexOptimize、CommandExecuteストアドプロシージャをデプロイ
   - オプションでSQL Agentジョブを自動作成
   - バックアップスケジュールの自動設定（WeeklyFull、DailyFull等）
2. **Update-DbaMaintenanceSolution**:
   - 既存のストアドプロシージャを最新バージョンに更新
   - テーブル、ジョブ、設定は保持
3. **Get-DbaMaintenanceSolutionLog**:
   - IndexOptimizeのテキストログファイルを解析
   - インデックス操作の詳細情報を取得

**画面遷移**：CLIコマンドのため画面遷移はありません。内部的にSave-DbaCommunitySoftwareを呼び出してソフトウェアをダウンロードします。

**権限による表示制御**：SQL Serverへの接続には適切な認証が必要です。ストアドプロシージャの作成およびSQL Agentジョブの作成には管理権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 313 | Install-DbaMaintenanceSolution | 主機能 | メンテナンスソリューションのインストール |
| 339 | Update-DbaMaintenanceSolution | 主機能 | メンテナンスソリューションの更新 |
| 248 | Get-DbaMaintenanceSolutionLog | 主機能 | メンテナンスログの取得 |

## 画面種別

コマンドライン（CLI）実行画面

## URL/ルーティング

```powershell
# インストール
Install-DbaMaintenanceSolution -SqlInstance <インスタンス名> [-Database <データベース名>] [-InstallJobs] [-CleanupTime <時間>]

# 更新
Update-DbaMaintenanceSolution -SqlInstance <インスタンス名> [-Database <データベース名>]

# ログ取得
Get-DbaMaintenanceSolutionLog -SqlInstance <インスタンス名> [-LogType IndexOptimize]
```

## 入出力項目

### Install-DbaMaintenanceSolution パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstance[] | Yes | - | ターゲットSQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 代替認証情報 |
| Database | string | No | master | インストール先データベース |
| BackupLocation | string | No | デフォルトバックアップパス | バックアップファイルの保存先 |
| CleanupTime | int | No | - | バックアップファイルの保持時間（時間単位） |
| OutputFileDirectory | string | No | - | ジョブ出力ファイルのディレクトリ |
| ReplaceExisting | switch | No | $false | 既存オブジェクトを置換 |
| LogToTable | switch | No | $false | CommandLogテーブルへのログ記録を有効化 |
| Solution | string[] | No | All | インストールするコンポーネント（All/Backup/IntegrityCheck/IndexOptimize） |
| InstallJobs | switch | No | $false | SQL Agentジョブを作成 |
| AutoScheduleJobs | string[] | No | - | 自動スケジュール設定（WeeklyFull/DailyFull/NoDiff/FifteenMinuteLog/HourlyLog） |
| StartTime | string | No | 011500 | ジョブ開始時刻（HHMMSS形式） |
| LocalFile | string | No | - | ローカルzipファイルパス |
| Force | switch | No | $false | キャッシュを無視して強制ダウンロード |
| InstallParallel | switch | No | $false | 並列実行用テーブルを作成 |
| ChangeBackupType | switch | No | $false | バックアップタイプの自動変換を有効化 |
| Compress | switch | No | - | バックアップ圧縮を有効化 |
| CopyOnly | switch | No | $false | コピーのみバックアップ |
| Verify | switch | No | - | バックアップ検証を有効化 |
| CheckSum | switch | No | - | チェックサム検証を有効化 |
| ModificationLevel | int | No | - | バックアップタイプ変換の変更レベル（0-100） |
| EnableException | switch | No | $false | 例外を有効化 |

### Update-DbaMaintenanceSolution パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstance[] | Yes | - | ターゲットSQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 代替認証情報 |
| Database | string | No | master | 対象データベース |
| Solution | string[] | No | All | 更新するコンポーネント（All/Backup/IntegrityCheck/IndexOptimize/CommandExecute） |
| LocalFile | string | No | - | ローカルzipファイルパス |
| Force | switch | No | $false | キャッシュを無視して強制ダウンロード |
| EnableException | switch | No | $false | 例外を有効化 |

### Get-DbaMaintenanceSolutionLog パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|------|-------------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | - | ターゲットSQL Serverインスタンス |
| SqlCredential | PSCredential | No | - | 代替認証情報 |
| LogType | string[] | No | IndexOptimize | ログタイプ（IndexOptimize/DatabaseBackup/DatabaseIntegrityCheck） |
| Since | datetime | No | - | 指定日時以降のログをフィルタ |
| Path | string | No | エラーログディレクトリ | ログファイルのパス |
| EnableException | switch | No | $false | 例外を有効化 |

## 表示項目

### Install-DbaMaintenanceSolution 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverホストコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Results | string | インストール結果（Success/Failed） |

### Update-DbaMaintenanceSolution 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverホストコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Solution | string | 更新されたソリューションコンポーネント |
| Procedure | string | 更新されたストアドプロシージャ名 |
| IsUpdated | bool | 更新成功フラグ |
| Results | string | 結果メッセージ（Updated/Procedure not installed/File not found） |

### Get-DbaMaintenanceSolutionLog 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverホストコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| StartTime | dbadatetime | 操作開始時刻 |
| Duration | timespan | 操作所要時間 |
| Index | string | インデックス名 |
| Statistics | string | 統計名 |
| Schema | string | スキーマ名 |
| Table | string | テーブル名 |
| Action | string | アクション（REBUILD/REORGANIZE） |
| Options | string | オプション |
| Fragmentation | string | 断片化率 |
| PageCount | string | ページ数 |
| Error | string | エラーメッセージ |

## イベント仕様

### 1-Install-DbaMaintenanceSolution実行時

1. Forceパラメータまたはキャッシュが存在しない場合、Save-DbaCommunitySoftwareを呼び出してダウンロード
2. インターネット接続がない場合は同梱のコピーを使用
3. 既存のMaintenance Solutionがある場合、ReplaceExistingが必要
4. SQL Serverインスタンスに接続
5. 必要なSQLファイルを選択（Solution、InstallJobs、InstallParallelに基づく）
6. パラメータに基づいてSQLスクリプトを変更
7. ReplaceExisting時は既存オブジェクトとジョブを削除
8. SQLスクリプトを順次実行
9. AutoScheduleJobs指定時はジョブスケジュールを作成
10. バックアップオプション（Compress、Verify、CheckSum等）をジョブステップに適用

### 2-Update-DbaMaintenanceSolution実行時

1. ローカルキャッシュを確認、必要に応じてダウンロード
2. SQL Serverインスタンスに接続
3. インストール済みプロシージャを確認
4. 各プロシージャに対応するSQLファイルを実行
5. 更新結果を出力

### 3-Get-DbaMaintenanceSolutionLog実行時

1. SQL Serverインスタンスに接続
2. ログディレクトリを特定（Pathパラメータまたはerrorlogpath）
3. IndexOptimize_*.txtファイルを検索
4. Since指定時はファイル日時でフィルタ
5. 各ログファイルを解析
6. インデックス/統計操作情報を抽出して出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Install | sys.procedures | INSERT | ストアドプロシージャ作成 |
| Install | dbo.CommandLog | CREATE | コマンドログテーブル作成 |
| Install | dbo.Queue, dbo.QueueDatabase | CREATE | 並列実行用テーブル作成 |
| Install | msdb.dbo.sysjobs | INSERT | SQL Agentジョブ作成 |
| Update | sys.procedures | UPDATE | ストアドプロシージャ更新 |

### 作成されるストアドプロシージャ

| プロシージャ名 | 説明 |
|---------------|------|
| CommandExecute | 共通コマンド実行プロシージャ |
| DatabaseBackup | データベースバックアッププロシージャ |
| DatabaseIntegrityCheck | データベース整合性チェックプロシージャ |
| IndexOptimize | インデックス最適化プロシージャ |

### 作成されるSQL Agentジョブ

| ジョブ名 | 説明 |
|---------|------|
| DatabaseBackup - SYSTEM_DATABASES - FULL | システムDBフルバックアップ |
| DatabaseBackup - USER_DATABASES - FULL | ユーザーDBフルバックアップ |
| DatabaseBackup - USER_DATABASES - DIFF | ユーザーDB差分バックアップ |
| DatabaseBackup - USER_DATABASES - LOG | ユーザーDBログバックアップ |
| DatabaseIntegrityCheck - SYSTEM_DATABASES | システムDB整合性チェック |
| DatabaseIntegrityCheck - USER_DATABASES | ユーザーDB整合性チェック |
| IndexOptimize - USER_DATABASES | ユーザーDBインデックス最適化 |
| CommandLog Cleanup | コマンドログクリーンアップ |
| Output File Cleanup | 出力ファイルクリーンアップ |
| sp_delete_backuphistory | バックアップ履歴削除 |
| sp_purge_jobhistory | ジョブ履歴削除 |

## メッセージ仕様

| 種別 | メッセージ | 発生条件 |
|------|----------|---------|
| エラー | Jobs can only be created for all solutions | Solutionが'All'以外でInstallJobs指定時 |
| エラー | CleanupTime is only useful when installing jobs | InstallJobsなしでCleanupTime指定時 |
| エラー | The Maintenance Solution already exists | ReplaceExistingなしで既存オブジェクトがある場合 |
| エラー | Database {Database} not found on {instance} | 指定データベースが存在しない場合 |
| 警告 | Parsing {LogType} is not supported at the moment | IndexOptimize以外のログタイプ指定時 |
| 警告 | No log files returned from {computername} | ログファイルが見つからない場合 |
| Verbose | No internet connection found, using included copy | インターネット接続なし時 |

## 例外処理

| 例外条件 | 動作 |
|---------|------|
| Solutionが'All'以外でInstallJobs指定 | Stop-Functionで処理を中断 |
| InstallJobsなしでCleanupTime指定 | Stop-Functionで処理を中断 |
| 接続エラー | Stop-Functionでエラーを報告し、次のインスタンスに継続 |
| データベース未存在 | Stop-Functionでエラーを報告し、次のインスタンスに継続 |
| 既存オブジェクト存在時（ReplaceExistingなし） | Stop-Functionで処理を中断 |
| SQLスクリプト実行エラー | Stop-Functionでエラーを報告、結果をFailedに設定 |

## 備考

- Ola Hallengren's Maintenance Solutionは業界標準のメンテナンスフレームワーク
- InstallJobsなしの場合はストアドプロシージャのみインストール
- AutoScheduleJobsは以下のスケジュールを自動設定:
  - WeeklyFull: 週次フル、日次差分、15分間隔ログバックアップ
  - DailyFull: 日次フル（差分なし）
  - HourlyLog: 時間単位ログバックアップ
- Get-DbaMaintenanceSolutionLogは現在IndexOptimizeログのみサポート
- sqlcmdで実行された場合のテキストログのみ解析可能

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaMaintenanceSolution.ps1 | `public/Install-DbaMaintenanceSolution.ps1` | Install出力オブジェクト（行811-816） |
| 1-2 | Update-DbaMaintenanceSolution.ps1 | `public/Update-DbaMaintenanceSolution.ps1` | Update出力オブジェクト（行147-155） |
| 1-3 | Get-DbaMaintenanceSolutionLog.ps1 | `public/Get-DbaMaintenanceSolutionLog.ps1` | ログ解析結果の構造（行136-148, 169-187） |

**読解のコツ**: Install-DbaMaintenanceSolutionの出力はシンプルですが、処理内容は非常に複雑です。AutoScheduleJobsの処理（行557-729）に注目してください。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaMaintenanceSolution.ps1 | `public/Install-DbaMaintenanceSolution.ps1` | パラメータ定義（行274-302）と前提条件チェック（行303-360） |
| 2-2 | Update-DbaMaintenanceSolution.ps1 | `public/Update-DbaMaintenanceSolution.ps1` | シンプルな更新ロジック（行120-181） |
| 2-3 | Get-DbaMaintenanceSolutionLog.ps1 | `public/Get-DbaMaintenanceSolutionLog.ps1` | ログファイル解析（行205-304） |

**主要処理フロー (Install)**:
1. **行303-360**: beginブロックでインターネット接続確認とダウンロード
2. **行362-413**: Get-DbaOlaWithParameters関数でSQLスクリプトのパラメータ置換
3. **行489-535**: ReplaceExisting時の既存オブジェクト削除
4. **行540-555**: SQLスクリプトの順次実行
5. **行557-729**: AutoScheduleJobsによるスケジュール作成
6. **行731-807**: バックアップオプションのジョブステップへの適用

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

```
Install-DbaMaintenanceSolution
    |
    +-- Save-DbaCommunitySoftware
    |      +-- GitHub/ローカルからダウンロード
    |
    +-- Connect-DbaInstance
    |      +-- SQL Server接続確立
    |
    +-- Get-DbaOlaWithParameters (内部関数)
    |      +-- SQLスクリプトのパラメータ置換
    |
    +-- Get-DbaModule
    |      +-- 既存プロシージャ確認
    |
    +-- Get-DbaDbTable
    |      +-- 既存テーブル確認
    |
    +-- Invoke-DbaQuery
    |      +-- SQLスクリプト実行
    |
    +-- Get-DbaAgentJob / Remove-DbaAgentJob
    |      +-- ジョブ管理
    |
    +-- New-DbaAgentSchedule
           +-- ジョブスケジュール作成

Update-DbaMaintenanceSolution
    |
    +-- Save-DbaCommunitySoftware
    |
    +-- Connect-DbaInstance
    |
    +-- Get-DbaModule
    |      +-- インストール済みプロシージャ確認
    |
    +-- Invoke-DbaQuery
           +-- SQLスクリプト実行

Get-DbaMaintenanceSolutionLog
    |
    +-- Connect-DbaInstance
    |
    +-- Join-AdminUnc
    |      +-- ログディレクトリパス変換
    |
    +-- process-block (内部関数)
           +-- ログブロック解析
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───────▶ Server SMO Object
      |
      v
GitHub/LocalFile ──▶ Save-DbaCommunitySoftware ──▶ ローカルキャッシュ
      |
      v
SQLスクリプト ─────▶ Get-DbaOlaWithParameters ───▶ パラメータ置換済みSQL
      |
      v
                    Invoke-DbaQuery ─────────────▶ ストアドプロシージャ作成
      |
      v
InstallJobs ────────▶ SQL Agentジョブ作成 ────────▶ 自動メンテナンス設定
      |
      v
AutoScheduleJobs ──▶ New-DbaAgentSchedule ───────▶ ジョブスケジュール
      |
      v
                    PSCustomObject生成 ─────────▶ インストール結果出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaMaintenanceSolution.ps1 | `public/Install-DbaMaintenanceSolution.ps1` | ソース | インストールコマンド |
| Update-DbaMaintenanceSolution.ps1 | `public/Update-DbaMaintenanceSolution.ps1` | ソース | 更新コマンド |
| Get-DbaMaintenanceSolutionLog.ps1 | `public/Get-DbaMaintenanceSolutionLog.ps1` | ソース | ログ取得コマンド |
| Save-DbaCommunitySoftware.ps1 | `public/Save-DbaCommunitySoftware.ps1` | ソース | ダウンロード機能 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Get-DbaModule.ps1 | `public/Get-DbaModule.ps1` | ソース | モジュール取得 |
| Get-DbaDbTable.ps1 | `public/Get-DbaDbTable.ps1` | ソース | テーブル取得 |
| New-DbaAgentSchedule.ps1 | `public/New-DbaAgentSchedule.ps1` | ソース | スケジュール作成 |
| Get-DbaAgentJob.ps1 | `public/Get-DbaAgentJob.ps1` | ソース | ジョブ取得 |
| Remove-DbaAgentJob.ps1 | `public/Remove-DbaAgentJob.ps1` | ソース | ジョブ削除 |
