# 画面設計書 176-データベースファイルデータ差分

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaDbExtentDiff` コマンドの機能仕様を定義した画面設計書です。

### 本画面の処理概要

本コマンドは、最終フルバックアップ以降に変更されたデータベースエクステントの割合を計算し、差分バックアップ戦略の判断を支援します。

**業務上の目的・背景**：差分バックアップと完全バックアップのどちらを実行すべきかは、最終フルバックアップ以降のデータ変更量に依存します。本コマンドは、エクステントレベル（8ページのグループ）での変更を分析し、正確な変更率を提供することで、DBAがバックアップスケジュールとストレージ要件を最適化するための情報を提供します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Get-DbaDbExtentDiff` コマンドを実行します。SQLインスタンスを必須パラメータとして指定します。

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスに接続
2. SQL Server 2016 SP2以降: sys.dm_db_file_space_usage DMVを使用
3. それ以前のバージョン: DBCC PAGEコマンドでDIFF_MAPページを直接解析
4. 総エクステント数と変更エクステント数から変更率を計算
5. 結果をPSCustomObjectとしてパイプラインに出力

**画面遷移**：本コマンドは単独実行可能です。出力結果は `Format-Table`、`Export-Csv` などの他のPowerShellコマンドにパイプで渡すことができます。

**権限による表示制御**：DBCC PAGE実行にはsysadmin権限が必要です。sys.dm_db_file_space_usageにはVIEW DATABASE STATE権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 102 | Get-DbaDbExtentDiff | 主機能 | データベースファイルエクステント差分の取得 |

## 画面種別

コマンドライン出力（一覧表示）

## URL/ルーティング

PowerShellコマンド: `Get-DbaDbExtentDiff`

## 入出力項目

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証用資格情報 |
| Database | object[] | No | 対象データベース（ワイルドカード対応） |
| ExcludeDatabase | object[] | No | 除外データベース（ワイルドカード対応） |
| EnableException | switch | No | 例外処理モードの有効化 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|---|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| DatabaseName | string | 分析対象データベース名 |
| ExtentsTotal | int | データベース内の総エクステント数 |
| ExtentsChanged | int | 最終フルバックアップ以降に変更されたエクステント数 |
| ChangedPerc | decimal | 変更されたデータベースの割合（小数点2桁） |

## イベント仕様

### 1-コマンド実行

1. SqlInstanceパラメータを検証
2. 指定されたインスタンスに接続（NonPooledConnection）
3. Database/ExcludeDatabaseパラメータでフィルタリング
4. 各データベースのアクセス可能性を確認
5. SQL Serverバージョンに応じた取得方法を選択：
   - 13.0.5026以降（2016 SP2）: sys.dm_db_file_space_usageをクエリ
   - それ以前: DBCC PAGEでDIFF_MAPを直接解析
6. 変更率を計算（小数点2桁に丸め）
7. PSCustomObjectを生成しパイプラインに出力
8. 非プール接続を切断

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行（2016 SP2以降） | sys.dm_db_file_space_usage | SELECT | 空間使用状況の取得 |
| コマンド実行（それ以前） | DBCC PAGE | SELECT | 差分マップページの解析 |

### テーブル別更新項目詳細

本コマンドは読み取り専用であり、データベースの更新は行いません。

## メッセージ仕様

| メッセージID | 種別 | 条件 | メッセージ内容 |
|-------------|------|------|--------------|
| M001 | Error | 接続失敗 | "Error occurred while establishing connection to {instance}" |
| M002 | Verbose | データベースアクセス不可 | "{db} is not accessible on {instance}, skipping" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラーを出力し、次のインスタンスに継続 |
| データベースアクセス不可 | Verboseメッセージを出力し、次のデータベースに継続 |

## 備考

- Paul S. Randalのオリジナルスクリプトに基づいています
- SQL Server 2016 SP2以降では効率的なDMVベースの分析が利用可能
- 古いバージョンではDBCC PAGEを使用するためパフォーマンスが低下する可能性があります
- エクステント = 8ページ（64KB）のグループ

---

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

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

### 推奨読解順序

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

出力オブジェクトのプロパティ構成を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbExtentDiff.ps1 | `public/Get-DbaDbExtentDiff.ps1` | 144-152行目、178-186行目：出力オブジェクトのプロパティ定義 |

**読解のコツ**: SQL Server 2016 SP2以降と以前のバージョンで出力処理が分かれています。

#### Step 2: バージョン分岐を理解する

SQL Serverバージョンによる処理分岐を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbExtentDiff.ps1 | `public/Get-DbaDbExtentDiff.ps1` | 134行目：バージョン判定 |

**主要処理フロー**:
- **134行目**: $server.Version -ge [version]'13.0.5026' でSQL Server 2016 SP2以降を判定
- **136-142行目**: DMVクエリ（sys.dm_db_file_space_usage）
- **154-186行目**: DBCC PAGEベースの処理

#### Step 3: DBCC PAGE処理を理解する

古いバージョン向けのDBCC PAGE解析処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbExtentDiff.ps1 | `public/Get-DbaDbExtentDiff.ps1` | 88-102行目：Get-DbaExtent関数 |
| 3-2 | Get-DbaDbExtentDiff.ps1 | `public/Get-DbaDbExtentDiff.ps1` | 163-176行目：DBCC PAGEループ |

**主要処理フロー**:
- **89行目**: 正規表現で':(?<extent>[\d]+)\)'パターンを定義
- **169-175行目**: extentIDを511232ずつインクリメントしてDIFF_MAPページを読み取り
- **173行目**: DIFF_MAP* かつ VALUE='CHANGED' の行を抽出

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

```
Get-DbaDbExtentDiff
    |
    +-- Connect-DbaInstance (NonPooledConnection)
    |
    +-- バージョン判定 ($server.Version >= 13.0.5026)
    |      |
    |      +-- [2016 SP2以降] sys.dm_db_file_space_usage クエリ
    |      |
    |      +-- [それ以前] DBCC PAGE ループ
    |             |
    |             +-- Get-DbaExtent (エクステント数計算)
    |
    +-- PSCustomObject (結果生成)
    |
    +-- Disconnect-DbaInstance (接続クローズ)
```

### データフロー図

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

SqlInstance   ---> Connect-DbaInstance  ---> $server
                        |
                        v
                  バージョン判定
                   /          \
                  /            \
      2016 SP2以降              以前
           |                      |
           v                      v
  sys.dm_db_file_          DBCC PAGE
  space_usage                  |
           |              Get-DbaExtent
           |                   |
           v                   v
      ExtentsTotal        ExtentsTotal
      ExtentsChanged      ExtentsChanged
           \                  /
            \                /
             v              v
          ChangedPerc = (Changed / Total) * 100
                        |
                        v
                  PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbExtentDiff.ps1 | `public/Get-DbaDbExtentDiff.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | ソース | 接続切断処理 |
