# 機能設計書 363-Test-DbaMigrationConstraint

## 概要

本ドキュメントは、SQL Serverインスタンス間のデータベース移行互換性を検証するための dbatools コマンド `Test-DbaMigrationConstraint` の機能設計を記述する。

### 本機能の処理概要

`Test-DbaMigrationConstraint` は、ソースSQL Serverインスタンスのデータベースがターゲットインスタンスに移行可能かどうかを事前検証するコマンドである。エディション固有の機能使用状況を分析し、移行の成否を予測する。

**業務上の目的・背景**：SQL Serverのエディション間（Enterprise/Developer/Standard/Express）でデータベースを移行する際、上位エディション固有の機能を使用しているデータベースは下位エディションへ移行できない。移行失敗は業務停止につながるため、事前に互換性を確認する必要がある。特にライセンス最適化でEnterprise→Standardへのダウングレードを検討する際に重要である。

**機能の利用シーン**：
- Enterprise EditionからStandard Editionへの移行計画時
- Developer Editionで開発したDBをStandard本番環境へ展開する前
- Express Editionへの移行時（SQL Agent非対応のためCDC使用不可）
- サーバー統合プロジェクトでの移行可否アセスメント

**主要な処理内容**：
1. ソースおよびターゲットサーバーへの接続確立
2. 対象データベースの抽出（フィルタリング）
3. バージョン互換性チェック（SQL 2000→2012+は不可、上位→下位は不可）
4. 照合順序の違いの警告
5. 各データベースについて:
   - FILESTREAM FileGroupの使用確認とFilestreamAccessLevel設定比較
   - sys.dm_db_persisted_sku_features DMVでエディション固有機能の検出
   - SQL Server 2016 SP1以降の機能平準化の考慮
   - Express Edition特有の制限（CDC + SQL Agent非対応）の検証
6. 移行可否判定結果の出力

**関連システム・外部連携**：sys.dm_db_persisted_sku_features DMV、sp_configure（FilestreamAccessLevel）

**権限による制御**：sysadmin推奨（DMVアクセス、sp_configure参照のため）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIツール | 主機能 | PowerShellコンソールから実行 |

## 機能種別

検証処理 / アセスメント

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstance | Yes | ソースSQL Serverインスタンス | SQL Server 2008以上 |
| SourceSqlCredential | PSCredential | No | ソースへの接続資格情報 | - |
| Destination | DbaInstance | Yes | ターゲットSQL Serverインスタンス | SQL Server 2008以上 |
| DestinationSqlCredential | PSCredential | No | ターゲットへの接続資格情報 | - |
| Database | object[] | No | 検証対象データベース名 | システムDB除外 |
| ExcludeDatabase | object[] | No | 検証除外データベース名 | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- sys.dm_db_persisted_sku_features DMV（各データベースから）
- sys.filegroups（FILESTREAM確認）
- sp_configure（FilestreamAccessLevel）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SourceInstance | String | ソースSQL Serverインスタンス名 |
| DestinationInstance | String | ターゲットSQL Serverインスタンス名 |
| SourceVersion | String | ソースエディション・SP・バージョン |
| DestinationVersion | String | ターゲットエディション・SP・バージョン |
| Database | String | データベース名 |
| FeaturesInUse | String | 使用中のエディション固有機能（カンマ区切り） |
| IsMigratable | Boolean | 移行可能かどうか |
| Notes | String | 移行可否の詳細理由 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック
   └─ エディション重み付けの定義
       ├─ Enterprise = 10, Developer = 10, Evaluation = 10
       ├─ Standard = 5
       └─ Express = 1

2. Process ブロック
   └─ ソース・ターゲットサーバー接続
   └─ データベース抽出とフィルタリング
   └─ バージョン検証:
       ├─ SQL 2000 → SQL 2012+: 不可
       ├─ 上位バージョン → 下位バージョン: 不可
       └─ 照合順序不一致: 警告
   └─ 各データベースについて:
       ├─ オフライン/アクセス不可: スキップ（警告）
       ├─ FILESTREAM FileGroup確認
       │   └─ FilestreamAccessLevel不一致: 移行不可
       ├─ sys.dm_db_persisted_sku_features照会
       ├─ SQL Server 2016 SP1 (13.0.4001.0)以降判定:
       │   ├─ Express + CDC: 移行不可
       │   └─ その他: 移行可能（機能平準化）
       └─ SQL Server 2016 SP1未満判定:
           ├─ 下位エディション + 機能使用: 移行不可
           └─ その他: 移行可能
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[サーバー接続]
    B --> C[データベース抽出]
    C --> D{システムDB?}
    D -->|Yes| E[エラー終了]
    D -->|No| F{SQL2000→2012+?}
    F -->|Yes| E
    F -->|No| G{上位→下位バージョン?}
    G -->|Yes| E
    G -->|No| H{照合順序一致?}
    H -->|No| I[警告出力]
    I --> J
    H -->|Yes| J[各DBループ]
    J --> K{オフライン?}
    K -->|Yes| L[警告・スキップ]
    L --> J
    K -->|No| M{FILESTREAM使用?}
    M -->|Yes| N{AccessLevel一致?}
    N -->|No| O[IsMigratable=false出力]
    O --> J
    N -->|Yes| P[SKU機能照会]
    M -->|No| P
    P --> Q{Dest >= 2016 SP1?}
    Q -->|Yes| R{Express + CDC?}
    R -->|Yes| O
    R -->|No| S[IsMigratable=true出力]
    Q -->|No| T{下位Edition + 機能使用?}
    T -->|Yes| O
    T -->|No| S
    S --> J
    J --> U{次のDB?}
    U -->|Yes| J
    U -->|No| V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | バージョン制約 | SQL 2000からSQL 2012以上への直接移行は不可 | SQL 2000ソース |
| BR-02 | 下位移行不可 | 上位バージョンから下位バージョンへの移行は不可 | 常に |
| BR-03 | FILESTREAM制約 | FilestreamAccessLevelが一致する必要あり | FILESTREAM使用時 |
| BR-04 | 2016 SP1機能平準化 | 2016 SP1以降は多くの機能がエディション間で利用可能 | Dest >= 13.0.4001.0 |
| BR-05 | Express CDC制約 | ExpressはSQL Agent非対応のためCDC使用DB移行不可 | Express + CDC |
| BR-06 | エディション重み | Enterprise/Developer/Evaluation=10, Standard=5, Express=1 | エディション比較時 |

### 計算ロジック

- エディション重み比較: `$editions.Item($destServer.Edition.ToString().Split(" ")[0])` vs ソースエディション
- バージョン番号変換: `[long]$destVersionNumber = $($destServer.VersionString).Replace(".", "")`
- 2016 SP1判定: `$destVersionNumber -ge 13040010`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読取 | sys.dm_db_persisted_sku_features | SELECT | エディション固有機能の検出 |
| 読取 | sys.filegroups | SELECT | FILESTREAM FileGroup確認 |
| 読取 | sys.configurations | SELECT | FilestreamAccessLevel取得（Get-DbaSpConfigure経由） |

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

#### sys.dm_db_persisted_sku_features

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | feature_name | 各データベースコンテキストで実行 | ChangeCapture, XTP等 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | ソース/ターゲットに接続できない | 接続情報確認 |
| - | バージョンエラー | SQL 2000→2012+移行試行 | 中間サーバー経由で移行 |
| - | バージョンエラー | 上位→下位バージョン移行 | スクリプト出力・手動再作成 |

### リトライ仕様

リトライ処理は実装されていない

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

読み取り専用操作のため、トランザクション管理は不要

## パフォーマンス要件

特に定義なし。データベース数に応じて処理時間が増加。

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

- sys.dm_db_persisted_sku_featuresはデータベースレベルの動的管理ビュー
- FilestreamAccessLevelの取得にはsp_configureアクセス権が必要
- 資格情報はPSCredentialオブジェクトで安全に取り扱う

## 備考

- SQL Server 2008 (v10) 以上が必要（sys.dm_db_persisted_sku_featuresの利用）
- オフラインデータベースは検証スキップ（警告出力）
- -Databaseパラメータはタブ補完対応

---

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

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

### 推奨読解順序

#### Step 1: エディション重み付けを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaMigrationConstraint.ps1 | `public/Test-DbaMigrationConstraint.ps1` | beginブロック（111-134行目）でエディション定義と定数を確認 |

**主要処理フロー**:
- **125-131行目**: エディション重み付けハッシュテーブル（Enterprise=10, Developer=10, Standard=5, Express=1）
- **132-133行目**: 移行可否メッセージの定数定義

#### Step 2: バージョン・照合順序検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaMigrationConstraint.ps1 | `public/Test-DbaMigrationConstraint.ps1` | processブロック（162-180行目）でバージョン検証を確認 |

**主要処理フロー**:
- **162-165行目**: SQL 2000→2012+移行ブロック
- **167-169行目**: 照合順序不一致警告
- **171-175行目**: 上位→下位バージョン移行ブロック

#### Step 3: FILESTREAM検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaMigrationConstraint.ps1 | `public/Test-DbaMigrationConstraint.ps1` | processブロック（202-222行目）でFILESTREAM検証を確認 |

**主要処理フロー**:
- **204行目**: FileStreamDataFileGroupの存在確認
- **206-207行目**: Get-DbaSpConfigureでFilestreamAccessLevel取得
- **209-221行目**: RunningValue比較と不一致時のfalse出力

#### Step 4: SKU機能検出と判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaMigrationConstraint.ps1 | `public/Test-DbaMigrationConstraint.ps1` | processブロック（224-303行目）でSKU機能検出と判定ロジックを確認 |

**主要処理フロー**:
- **225行目**: sys.dm_db_persisted_sku_featuresクエリ
- **243行目**: 2016 SP1 (13.0.4001.0)以降の判定
- **248行目**: Express + CDC組み合わせの検出
- **278行目**: 下位エディション + 機能使用時の判定

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

```
Test-DbaMigrationConstraint
    │
    ├─ Connect-DbaInstance (ソース接続)
    │
    ├─ Connect-DbaInstance (ターゲット接続)
    │
    ├─ Get-DbaSpConfigure -ConfigName FilestreamAccessLevel
    │
    └─ $sourceServer.Query("SELECT feature_name FROM sys.dm_db_persisted_sku_features")
```

### データフロー図

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

Source Instance ───────▶ バージョン/照合順序検証
        │                       │
        │                       ▼
        │               各DBのFILESTREAM確認
        │                       │
        │                       ▼
        └───────────▶ sys.dm_db_persisted_sku_features
                                │
                                ▼
Destination Instance ───▶ エディション比較・判定 ───▶ PSCustomObject
                                                    (IsMigratable/Notes)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaMigrationConstraint.ps1 | `public/Test-DbaMigrationConstraint.ps1` | ソース | メインコマンド実装 |
| Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | ソース | sp_configure値取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ヘルパー |
