# 機能設計書 103-Get-DbaDbFeatureUsage

## 概要

本ドキュメントは、SQL Server Enterprise版固有の機能の使用状況を特定するGet-DbaDbFeatureUsage機能の設計仕様を定義する。

### 本機能の処理概要

本機能は、sys.dm_db_persisted_sku_features動的管理ビュー（DMV）を使用して、データベース内で使用されているSQL Server Enterprise版固有の機能を特定する。これにより、Enterprise版からStandard版へのダウングレードや、異なるエディションへの移行を計画する際のブロッキング要因を事前に把握できる。

**業務上の目的・背景**：SQL Serverのライセンスコスト削減のためにEnterprise版からStandard版へのダウングレードを検討する際、列ストアインデックス、テーブルパーティショニング、透過的データ暗号化（TDE）などのEnterprise機能が使用されていると移行がブロックされる。本機能はこれらのブロッキング機能を事前に特定し、必要な是正措置を計画するために使用される。

**機能の利用シーン**：
- SQL Serverエディションのダウングレード計画前の事前調査
- ライセンス監査とコスト最適化の分析
- クラウド移行時のエディション選定判断
- Enterprise機能の使用状況レポート作成

**主要な処理内容**：
1. 対象データベースの取得（パイプライン入力またはSqlInstanceパラメータから）
2. データベースのアクセシビリティチェック
3. sys.dm_db_persisted_sku_features DMVへのクエリ実行
4. Enterprise機能の使用情報を構造化された形式で出力

**関連システム・外部連携**：SQL Serverのsys.dm_db_persisted_sku_features DMVを使用してEnterprise機能の永続的な使用状況を取得する。

**権限による制御**：DMVへのアクセスにはVIEW DATABASE STATE権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 直接の画面関連なし（監査・分析用途） |

## 機能種別

データ取得・分析処理（監査機能）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証、AD統合認証 |
| Database | string[] | No | 対象データベース名 | ワイルドカード対応 |
| ExcludeDatabase | string[] | No | 除外するデータベース名 | ワイルドカード対応 |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプライン入力用データベースオブジェクト | SMOデータベースオブジェクト |
| EnableException | switch | No | 例外処理モードの切り替え | - |

### 入力データソース

- SqlInstance: コマンドラインパラメータ
- InputObject: Get-DbaDatabaseなどからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（デフォルトは'MSSQLSERVER'） |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Id | int | 機能ID（feature_id） |
| Feature | string | Enterprise機能名（feature_name） |
| Database | string | 機能が検出されたデータベース名 |

### 出力先

PowerShellパイプライン（クエリ結果のDataRow）

## 処理フロー

### 処理シーケンス

```
1. SQLクエリの初期化
   └─ sys.dm_db_persisted_sku_featuresを参照するクエリを準備
2. インスタンスごとのデータベース取得
   └─ Get-DbaDatabaseを使用してフィルタリング
3. データベースごとの処理ループ
   └─ アクセシビリティチェック
   └─ DMVクエリの実行
4. 結果の出力
   └─ Enterprise機能が存在する場合のみ出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ初期化]
    B --> C{SqlInstance指定?}
    C -->|Yes| D[Get-DbaDatabase呼び出し]
    D --> E[InputObjectに追加]
    C -->|No| E
    E --> F{データベースループ}
    F -->|次のDB| G{IsAccessible?}
    G -->|No| H[エラー出力・スキップ]
    H --> F
    G -->|Yes| I[DMVクエリ実行]
    I --> J{クエリ成功?}
    J -->|No| K[エラー出力]
    K --> F
    J -->|Yes| L[結果出力]
    L --> F
    F -->|完了| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-301 | アクセシビリティチェック | アクセス不可能なデータベースはスキップし警告を出力 | データベースループ時 |
| BR-302 | 結果なしの扱い | Enterprise機能が使用されていない場合は出力なし | クエリ結果なし時 |

### 計算ロジック

特に計算ロジックはなく、DMVからの直接取得。

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

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

| 操作 | 対象テーブル/ビュー | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Enterprise機能取得 | sys.dm_db_persisted_sku_features | SELECT | SKU固有の永続化機能を取得 |

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

#### sys.dm_db_persisted_sku_features

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | feature_id | 機能の一意識別子 | - |
| SELECT | feature_name | 機能名 | 例：Columnstore, Compression, Partitioning |

**検出可能なEnterprise機能の例**：
- Columnstore（列ストアインデックス）
- Compression（データ圧縮）
- Partitioning（テーブルパーティショニング）
- TDE（透過的データ暗号化）
- Change Data Capture
- Online Index Operation

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | データベースがアクセス不可 | スキップして次のDBを処理 |
| - | Stop-Function | クエリ実行失敗 | エラー出力して次のDBを処理 |

### リトライ仕様

リトライは実装されていない。エラー発生時は次のデータベースの処理を継続。

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

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

## パフォーマンス要件

DMVへの単純なSELECTクエリのため、高速に動作（ミリ秒単位）。

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

- VIEW DATABASE STATE権限が必要
- SqlCredentialパラメータで代替認証情報をサポート
- 機密情報（暗号化設定等）の露出に注意

## 備考

- Tags: Deprecated と記載されているが、機能自体は有効
- Standard版への移行時の重要な事前調査ツール

---

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

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

### 推奨読解順序

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

DMVクエリの構造と出力形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbFeatureUsage.ps1 | `public/Get-DbaDbFeatureUsage.ps1` | 88-91行目：SQLクエリ定義 |

**読解のコツ**: beginブロックで定義されるSQLクエリが出力の構造を決定している。SERVERPROPERTY関数を使用してインスタンス情報を取得し、DMVからfeature_idとfeature_nameを取得している。

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

パラメータ定義とprocessブロックの構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbFeatureUsage.ps1 | `public/Get-DbaDbFeatureUsage.ps1` | 76-85行目：パラメータ定義 |

**主要処理フロー**:
1. **88-91行目**: SQLクエリの準備（beginブロック）
2. **95-97行目**: SqlInstance指定時のGet-DbaDatabase呼び出し
3. **98-99行目**: データベースループ開始
4. **101-103行目**: アクセシビリティチェック
5. **105-109行目**: クエリ実行と結果出力

#### Step 3: エラーハンドリングを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbFeatureUsage.ps1 | `public/Get-DbaDbFeatureUsage.ps1` | 101-109行目：エラー処理 |

**主要処理フロー**:
- **101-103行目**: IsAccessible=falseの場合Stop-Functionでスキップ
- **107-109行目**: try-catchでクエリエラーをハンドリング

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

```
Get-DbaDbFeatureUsage
    │
    ├─ Get-DbaDatabase（SqlInstance指定時）
    │      └─ Connect-DbaInstance
    │
    ├─ Write-Message（ログ出力）
    │
    ├─ Stop-Function（エラー処理）
    │
    └─ $db.Query()（DMVクエリ実行）
```

### データフロー図

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

SqlInstance ───▶ Get-DbaDatabase ───┐
                                    │
Database ───────────────────────────┤
                                    ▼
InputObject ──────────────────▶ ループ処理
                                    │
                                    ▼
                            ┌─────────────────┐
                            │ DMVクエリ実行   │
                            │ sys.dm_db_     │
                            │ persisted_     │
                            │ sku_features   │
                            └────────┬────────┘
                                     │
                                     ▼
                              ┌────────────┐      ┌─ ComputerName
                              │ DataRow    │──────┼─ InstanceName
                              └────────────┘      ├─ SqlInstance
                                                  ├─ Id
                                                  ├─ Feature
                                                  └─ Database
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbFeatureUsage.ps1 | `public/Get-DbaDbFeatureUsage.ps1` | ソース | メイン処理 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
