# 機能設計書 385-Update-DbaInstance

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるUpdate-DbaInstance機能の設計仕様を記載する。本機能は、ローカルおよびリモートのSQL ServerインスタンスにService PackおよびCumulative Updateを自動的にインストールする。

### 本機能の処理概要

本機能は、SQL Serverパッチ適用の全プロセスを自動化し、複数インスタンスの更新における手動作業を排除する。検出からインストールまでの完全なパッチ適用ワークフローを処理し、各サーバーへのRDP接続、パッチファイルのコピー、インストーラー実行、更新追跡といった手動プロセスを置き換える。

**業務上の目的・背景**：月次パッチ適用サイクル、緊急セキュリティ更新、または開発環境を本番パッチレベルに合わせるなど、SQL Server環境全体のパッチ管理は時間がかかり、ミスが発生しやすい作業である。本機能により、一貫した信頼性の高いパッチ適用プロセスを実現できる。

**機能の利用シーン**：
- 月次セキュリティパッチ適用サイクル
- 緊急セキュリティ更新の展開
- 開発/テスト環境を本番環境のパッチレベルに同期
- 新規インスタンスのパッチレベル標準化
- 特定KBの緊急適用

**主要な処理内容**：
1. レジストリスキャンによる対象コンピュータ上のSQL Serverインスタンス検出
2. 現在のバージョンと目標更新要件の検証
3. パッチリポジトリ内の適切なKBインストーラーの特定
4. CredSSP等のプロトコルによるセキュアなリモート接続確立
5. 一時ディレクトリからのパッチ抽出・実行
6. 必要に応じた再起動と複数更新の連鎖適用
7. インストール後の一時ファイルクリーンアップ
8. 並列処理による複数コンピュータの高速展開

**関連システム・外部連携**：パッチファイルリポジトリ（ネットワーク共有またはローカル）、PowerShellリモーティング（WinRM）、CredSSP認証。

**権限による制御**：対象コンピュータ上でのローカル管理者権限が必要。リモートサーバーでの実行にはCredSSP設定が推奨。

## 関連画面

本機能はCLIベースのPowerShellコマンドレットであり、GUI画面との直接的な関連はない。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | PowerShellコンソール | 主画面 | コマンド実行とパッチ適用状況表示 |

## 機能種別

システム更新 / インストール処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ名。デフォルトはローカル | パイプライン入力可 |
| Credential | PSCredential | No | リモートサーバー接続用Windows資格情報 | - |
| Version | string[] | No | 目標バージョンパターン（例: "2016SP2CU3"） | 正規表現検証 |
| Type | string[] | No | 更新タイプ（All/ServicePack/CumulativeUpdate） | ValidateSet |
| KB | string[] | No | 特定KB番号での更新 | KB形式検証 |
| InstanceName | string | No | 特定インスタンス名に限定 | - |
| Path | string[] | No | パッチファイルリポジトリのパス | - |
| Restart | switch | No | インストール後の自動再起動 | - |
| Continue | switch | No | 失敗したインストールの再開 | - |
| Authentication | string | No | リモーティング認証方式 | ValidateSet |
| UseSSL | switch | No | SSL暗号化WinRM接続 | - |
| Port | int | No | WinRMポート番号 | - |
| Throttle | int | No | 並列処理の最大数。デフォルト50 | - |
| ArgumentList | string[] | No | インストーラーへの追加引数 | - |
| Download | switch | No | 不足パッチの自動ダウンロード | - |
| NoPendingRenameCheck | switch | No | 保留中のリネームチェックをスキップ | - |
| ExtractPath | string | No | パッチ抽出先ディレクトリ | - |
| WhatIf | switch | No | 実行せず影響を表示 | - |
| Confirm | switch | No | 実行前に確認を要求 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- パイプライン入力：ComputerNameがValueFromPipelineをサポート
- パッチリポジトリ：-Pathで指定されたフォルダまたはPath.SQLServerUpdates設定値
- オンライン：-Download指定時はMicrosoftからダウンロード

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | 対象コンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| MajorVersion | int | SQL Serverメジャーバージョン番号 |
| TargetLevel | string | 適用された目標パッチレベル |
| KB | string | インストールされたKB番号 |
| Installer | string | 実行されたインストーラーのフルパス |
| Successful | bool | インストール成功/失敗 |
| Restarted | bool | サーバー再起動の有無 |
| Notes | object[] | インストール過程のメッセージ |

### 出力先

PowerShellパイプラインへPSCustomObjectとして出力。

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ Version/KBパラメータの形式検証
   └─ アクションリスト構築
2. 各コンピュータの処理準備
   └─ ネットワーク名解決
   └─ 保留中の再起動チェック
   └─ リモート接続テスト（CredSSP等）
3. SQL Serverインスタンス検出
   └─ レジストリからコンポーネント取得
   └─ 現在のバージョン確認
4. 各アクションの更新詳細取得
   └─ Get-SqlInstanceUpdateで目標バージョン決定
   └─ Find-SqlInstanceUpdateでインストーラー検索
5. ダウンロード（必要な場合）
   └─ Save-DbaKbUpdateでKBダウンロード
   └─ リモートサーバーへファイル転送
6. パッチインストール実行
   └─ Invoke-DbaAdvancedUpdateで実際のインストール
   └─ 並列処理（複数サーバー時）
7. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[パラメータ検証]
    B --> C[アクションリスト構築]
    C --> D[各コンピュータでループ]
    D --> E[ネットワーク名解決]
    E --> F{保留中の再起動?}
    F -->|Yes| G{Restart指定?}
    G -->|No| H[エラー: 再起動必要]
    G -->|Yes| I[リモート接続テスト]
    F -->|No| I
    I --> J{接続成功?}
    J -->|No| K[CredSSP設定試行]
    J -->|Yes| L[SQL Serverインスタンス検出]
    K --> L
    L --> M[各アクションでループ]
    M --> N[更新詳細取得]
    N --> O{インストーラー存在?}
    O -->|No| P{Download指定?}
    P -->|Yes| Q[KBダウンロード]
    P -->|No| R[エラー: インストーラーなし]
    Q --> S[インストールアクション追加]
    O -->|Yes| S
    S --> T{次のアクションあり?}
    T -->|Yes| M
    T -->|No| U[ShouldProcess確認]
    U --> V[Invoke-DbaAdvancedUpdate]
    V --> W[結果出力]
    W --> X{次のコンピュータあり?}
    X -->|Yes| D
    X -->|No| Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Version形式 | <MajorVersion><SPX><CUX>形式（例: 2016SP2CU3） | Version指定時 |
| BR-002 | KB形式 | 数字のみまたはKBプレフィックス付き | KB指定時 |
| BR-003 | 認証デフォルト | Credential指定時はCredSSP、それ以外はDefault | 常時 |
| BR-004 | 再起動必須 | 複数更新の連鎖にはRestart指定が必要 | 複数パッチ適用時 |
| BR-005 | 並列処理 | 複数サーバー時はInvoke-Parallelで並列実行 | installActions.Count >= 2 |
| BR-006 | ConfirmImpact | High設定のため、-Confirm:$falseで自動化 | 常時 |

### 計算ロジック

認証方式決定:
```powershell
$Authentication = @('Credssp', 'Default')[$null -eq $Credential]
```

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

本機能はSQL Serverのパッチを適用するが、直接的なT-SQL実行は行わない。

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| なし | - | - | パッチインストーラーの実行（SQL Serverサービスレベル） |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| InvalidArgument | パラメータエラー | Version形式不正 | 正しいVersion形式を指定 |
| InvalidArgument | パラメータエラー | KB形式不正 | 正しいKB形式を指定 |
| - | 接続エラー | リモート接続失敗 | 認証情報・ネットワーク確認 |
| - | インストーラー不在 | パッチファイルが見つからない | -Downloadまたは正しいPath指定 |
| - | 保留中の再起動 | 再起動が必要な状態 | 先に再起動を実行 |
| - | SQL Server不在 | インスタンスが見つからない | 対象コンピュータを確認 |

### リトライ仕様

-Continue パラメータで失敗したインストールを再開可能。

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

パッチインストールはSQL Serverインストーラーが管理。ロールバックはインストーラーレベル。

## パフォーマンス要件

- 並列処理で複数サーバーを同時更新（デフォルトThrottle=50）
- ネットワーク帯域とパッチファイルサイズに依存
- 大規模環境ではThrottle値の調整を推奨

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

- CredSSP認証は管理者権限のPowerShellセッションが必要
- パッチファイルリポジトリへのアクセス権限が必要
- リモートサーバーでのローカル管理者権限が必要
- SSL接続（-UseSSL）でセキュアな通信可能
- 常にデータベースと設定のバックアップを推奨

## 備考

- ConfirmImpact = 'High' のため、対話的確認がデフォルト
- commands.initialize-credssp.bypass設定でCredSSP自動設定を無効化可能
- SupportsShouldProcessでWhatIfとConfirmをサポート

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Update-DbaInstance.ps1 | `public/Update-DbaInstance.ps1` | 出力オブジェクト構造（129-143行目の.OUTPUTS） |

**読解のコツ**: 出力はSelect-DefaultViewで表示プロパティが制限される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Update-DbaInstance.ps1 | `public/Update-DbaInstance.ps1` | パラメータ定義（222-254行目） |
| 2-2 | Update-DbaInstance.ps1 | `public/Update-DbaInstance.ps1` | beginブロック（255-431行目） |

**主要処理フロー**:
1. **222-254行目**: パラメータ定義。ParameterSetでVersionとKBを分離
2. **259-276行目**: Version/KB形式の検証
3. **277-338行目**: アクションリストの構築
4. **350-373行目**: Join-AdminUnc内部関数（UNCパス変換）
5. **374-416行目**: Copy-UncFile内部関数（リモートファイルコピー）
6. **417-431行目**: Test-NetworkPath内部関数

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Update-DbaInstance.ps1 | `public/Update-DbaInstance.ps1` | コンピュータループ（440-609行目） |
| 3-2 | Update-DbaInstance.ps1 | `public/Update-DbaInstance.ps1` | ダウンロード処理（610-660行目） |
| 3-3 | Update-DbaInstance.ps1 | `public/Update-DbaInstance.ps1` | インストール実行（662-682行目） |

**主要処理フロー**:
- **461-468行目**: Get-SQLInstanceComponentでインスタンス検出
- **474-487行目**: 保留中の再起動チェック
- **489-541行目**: リモート接続テストとCredSSP設定
- **544-597行目**: 各アクションの更新詳細取得
- **611-628行目**: Save-DbaKbUpdateでKBダウンロード
- **663-676行目**: installScriptでInvoke-DbaAdvancedUpdate呼び出し
- **678-682行目**: 並列/順次実行の判定

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

```
Update-DbaInstance
    │
    ├─ Resolve-DbaNetworkName
    │      └─ コンピュータ名解決
    │
    ├─ Test-PendingReboot
    │      └─ 保留中の再起動チェック
    │
    ├─ Get-SQLInstanceComponent
    │      └─ レジストリからSQL Server検出
    │
    ├─ Get-SqlInstanceUpdate
    │      └─ 目標バージョン決定
    │
    ├─ Find-SqlInstanceUpdate
    │      └─ インストーラー検索
    │
    ├─ Save-DbaKbUpdate
    │      └─ KBダウンロード
    │
    ├─ Copy-UncFile (内部関数)
    │      └─ リモートファイルコピー
    │
    ├─ Initialize-CredSSP
    │      └─ CredSSP設定
    │
    ├─ Invoke-DbaAdvancedUpdate
    │      └─ 実際のパッチインストール
    │
    └─ Invoke-Parallel
           └─ 複数サーバーの並列処理
```

### データフロー図

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

ComputerName ───┐
                │
Version/KB ─────┤
                │
Path ───────────┼──▶ インスタンス検出 ──▶ PSCustomObject
                │    ▼                     │
Credential ─────┤    更新詳細取得          ├─ ComputerName
                │    ▼                     ├─ InstanceName
パッチファイル ──┘    インストーラー検索    ├─ MajorVersion
(リポジトリ)         ▼                     ├─ TargetLevel
                     Invoke-DbaAdvanced    ├─ KB
                     Update                ├─ Successful
                                           └─ Notes
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Update-DbaInstance.ps1 | `public/Update-DbaInstance.ps1` | ソース | メイン機能実装 |
| Update-DbaInstance.Tests.ps1 | `tests/Update-DbaInstance.Tests.ps1` | テスト | 単体テスト |
| Invoke-DbaAdvancedUpdate.ps1 | `public/Invoke-DbaAdvancedUpdate.ps1` | 依存 | 実際のパッチ実行 |
| Save-DbaKbUpdate.ps1 | `public/Save-DbaKbUpdate.ps1` | 依存 | KBダウンロード |
| Get-DbaBuild.ps1 | `public/Get-DbaBuild.ps1` | 依存 | ビルド情報取得 |
