# 機能設計書 218-Set-DbaDbCompatibility

## 概要

本ドキュメントは、データベース互換性レベルを変更するSet-DbaDbCompatibility関数の機能設計書です。

### 本機能の処理概要

Set-DbaDbCompatibilityは、1つ以上のSQL Serverインスタンス上のデータベース互換性レベルを更新します。特定の互換性レベルが指定されていない場合、各データベースをそれが存在するSQL Serverインスタンスのバージョンに合わせて自動的に設定します。これはSQL Serverアップグレード後にデータベースが元の互換性レベルを保持しており、新しいエンジン機能と最適化を活用するために更新が必要な場合に特に役立ちます。

**業務上の目的・背景**：SQL Serverをアップグレードした後、データベースは以前のバージョンの互換性レベルを維持します。新しいバージョンのクエリオプティマイザ機能やパフォーマンス最適化を活用するには、互換性レベルを新しいバージョンに合わせて更新する必要があります。本機能は、複数のデータベースに対する互換性レベルの一括更新を効率化します。

**機能の利用シーン**：
- SQL Serverアップグレード後に互換性レベルを更新する場合
- 複数データベースの互換性レベルを一括で変更する場合
- 特定の互換性レベルに統一する場合
- 互換性レベルの現状確認と更新を同時に行う場合

**主要な処理内容**：
1. 対象データベースの取得（SqlInstanceまたはInputObject）
2. ターゲット互換性レベルの決定（指定値またはインスタンスバージョンに基づく自動決定）
3. 現在のレベルとターゲットレベルの比較
4. 異なる場合のみ互換性レベルを更新
5. 更新結果の出力

**関連システム・外部連携**：
- SQL Server Management Objects (SMO)
- SQL Serverデータベースエンジン

**権限による制御**：データベースに対するALTER権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIインターフェース | 主画面 | コマンドライン実行 |

## 機能種別

構成変更 / データベース管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | インスタンス名 |
| SqlCredential | PSCredential | No | 認証用資格情報 | PSCredential型 |
| Database | string[] | No | 対象データベース名 | ワイルドカード対応 |
| Compatibility | CompatibilityLevel | No | ターゲット互換性レベル | Version80〜Version170等 |
| InputObject | Database[] | No | パイプライン入力 | SMO Databaseオブジェクト |
| EnableException | switch | No | 例外を有効化 | スイッチ型 |
| WhatIf | switch | No | 実行シミュレーション | スイッチ型 |
| Confirm | switch | No | 確認プロンプト | スイッチ型 |

### 入力データソース

- SqlInstance指定によるデータベース取得
- Get-DbaDatabase等からのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| Compatibility | CompatibilityLevel | 新しい互換性レベル |
| PreviousCompatibility | CompatibilityLevel | 変更前の互換性レベル |

### 出力先

- パイプライン出力（PSCustomObject）
- 互換性レベルが既にターゲットと一致している場合は出力なし

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ SqlInstance/InputObjectのいずれかを確認

2. データベース取得
   └─ Get-DbaDatabase（SqlInstance指定時）

3. 各データベースの処理
   ├─ 現在の互換性レベル取得
   ├─ ターゲットレベル決定（指定または自動）
   ├─ レベル比較
   └─ 異なる場合のみ更新

4. 更新処理
   └─ Database.CompatibilityLevel設定、Alter()実行

5. 結果出力
   └─ PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance or InputObject?}
    B -->|Neither| C[警告メッセージ]
    B -->|SqlInstance| D[Get-DbaDatabase]
    B -->|InputObject| E[InputObjectを使用]

    D --> E
    E --> F[各DBをループ]
    C --> G[次のデータベース]

    F --> H[現在のレベル取得]
    H --> I{Compatibility指定?}
    I -->|Yes| J[指定値を使用]
    I -->|No| K[インスタンスバージョンから算出]

    J --> L{現在 != ターゲット?}
    K --> L
    L -->|No| M[Verboseログ出力]
    L -->|Yes| N{ShouldProcess確認}

    M --> G
    N -->|No| G
    N -->|Yes| O[CompatibilityLevel設定]

    O --> P[Alter()実行]
    P --> Q[PSCustomObject出力]
    Q --> G

    G --> R{次のDB?}
    R -->|Yes| F
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 入力必須 | SqlInstanceまたはInputObjectのいずれかが必須 | 常時 |
| BR-002 | 自動レベル決定 | Compatibility未指定時はインスタンスバージョンから算出 | Compatibility未指定 |
| BR-003 | 条件付き更新 | 現在のレベルとターゲットが異なる場合のみ更新 | 常時 |
| BR-004 | レベル算出式 | Version${VersionMajor}0形式で算出 | 自動決定時 |

### 計算ロジック

```powershell
# 互換性レベル自動算出
$targetCompatibility = [Microsoft.SqlServer.Management.Smo.CompatibilityLevel]"Version$($serverVersion)0"
# 例: SQL Server 2019 (VersionMajor=15) → Version150
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 互換性レベル変更 | sys.databases | UPDATE | 互換性レベルの更新 |

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

SMO経由でのALTER DATABASE SET COMPATIBILITY_LEVEL実行。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 入力不足 | SqlInstance/InputObject両方未指定 | 警告メッセージ出力、処理継続 |
| - | 更新失敗 | Alter()実行失敗 | Stop-Functionで継続処理 |

### リトライ仕様

リトライは行いません。エラー発生時は次のデータベースへ継続処理します。

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

SMOのAlter()メソッド内でトランザクション管理されます。互換性レベル変更は即座に反映されます。

## パフォーマンス要件

特になし。互換性レベル変更は軽量なメタデータ操作です。

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

- データベースに対するALTER権限が必要
- 互換性レベル変更は接続中のユーザーに影響を与える可能性あり

## 備考

- 互換性レベルの変更はクエリオプティマイザの動作に影響
- 互換性レベルを下げることも可能だが、アプリケーションへの影響を確認が必要
- バージョン対応: Version80(SQL 2000)〜Version170(SQL 2025)

---

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

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

### 推奨読解順序

#### Step 1: パラメータ定義を理解する

関数のパラメータ構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaDbCompatibility.ps1 | `public/Set-DbaDbCompatibility.ps1` 86-95行目 | パラメータ定義 |

**読解のコツ**: CompatibilityパラメータはMicrosoft.SqlServer.Management.Smo.CompatibilityLevel列挙型を使用します。

#### Step 2: データベース取得処理を理解する

対象データベースの取得ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaDbCompatibility.ps1 | `public/Set-DbaDbCompatibility.ps1` 96-104行目 | 入力検証、DB取得 |

**主要処理フロー**:
1. **97-100行目**: SqlInstance/InputObject両方未指定時の警告
2. **102-104行目**: SqlInstance指定時のGet-DbaDatabase呼び出し

#### Step 3: 互換性レベル決定ロジックを理解する

ターゲット互換性レベルの決定方法を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbCompatibility.ps1 | `public/Set-DbaDbCompatibility.ps1` 106-117行目 | レベル決定ロジック |

**主要処理フロー**:
- **106-108行目**: サーバーオブジェクトと現在のレベル取得
- **111-112行目**: Compatibility指定時は指定値を使用
- **113-116行目**: 未指定時はVersionMajorから算出

#### Step 4: 更新処理と出力を理解する

実際の更新処理と結果出力を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaDbCompatibility.ps1 | `public/Set-DbaDbCompatibility.ps1` 119-140行目 | 更新実行、結果出力 |

**主要処理フロー**:
- **119行目**: レベル比較
- **120行目**: ShouldProcess確認
- **122-123行目**: CompatibilityLevel設定、Alter()実行
- **125-132行目**: PSCustomObject出力（変更前後のレベル含む）
- **137-138行目**: レベル一致時のVerboseログ

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

```
Set-DbaDbCompatibility
    │
    ├─ Test-Bound (パラメータ指定確認)
    │
    ├─ Get-DbaDatabase (DB取得)
    │      └─ Connect-DbaInstance
    │
    ├─ Database.CompatibilityLevel (プロパティ設定)
    │
    ├─ Database.Alter() (SMO更新)
    │
    └─ Stop-Function (エラー処理)
```

### データフロー図

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

SqlInstance        ───▶ Get-DbaDatabase       ───▶
     or                       │
InputObject                   ▼
     +             ───▶ レベル決定            ───▶
Compatibility                 │
                              ▼
               ───▶ 比較・更新実行         ───▶ PSCustomObject
                              │                    (変更されたDBのみ)
                              ▼
                 ───▶ Database.Alter()
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaDbCompatibility.ps1 | `public/Set-DbaDbCompatibility.ps1` | ソース | メイン関数 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータ指定確認 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
