# 機能設計書 107-Get-DbaDbPageInfo

## 概要

本ドキュメントは、SQL Serverデータベースの詳細なページ割り当て情報を取得するGet-DbaDbPageInfo機能の設計仕様を定義する。

### 本機能の処理概要

本機能は、sys.dm_db_database_page_allocations動的管理ビューを使用して、ページ割り当ての詳細情報（ページタイプ、空き領域率、割り当て状態、混合ページ割り当てフラグ）を取得する。ストレージの問題のトラブルシューティング、空間利用パターンの分析、ページレベルのパフォーマンス問題の調査に使用される。

**業務上の目的・背景**：データベースのストレージ効率を理解することは、パフォーマンス最適化とコスト管理において重要である。ページレベルの詳細情報により、断片化の特定、未使用領域の把握、ストレージ利用パターンの分析が可能になる。

**機能の利用シーン**：
- ストレージ問題のトラブルシューティング
- ページ断片化の分析
- 空間利用パターンの調査
- インデックス再構築の判断材料
- データベースの詳細な物理構造分析

**主要な処理内容**：
1. SQL Server 2012以上への接続（MinimumVersion 11）
2. 対象データベースの取得
3. sys.dm_db_database_page_allocationsへのクエリ実行
4. ページ割り当て情報の出力

**関連システム・外部連携**：SQL Server 2012以降のsys.dm_db_database_page_allocations DMVを使用。

**権限による制御**：VIEW DATABASE STATE権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 62 | 空間・メモリ情報 | 関連機能 | データベース空間使用量の取得と関連 |

## 機能種別

データ取得・分析処理（Storage analysis）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象のSQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証、AD統合認証 |
| Database | string[] | No | 対象データベース名 | ワイルドカード対応 |
| Schema | string[] | No | 対象スキーマ名 | 複数指定可 |
| Table | 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インスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| Schema | string | スキーマ名 |
| Table | string | テーブル名 |
| PageType | string | ページタイプ（DATA_PAGE、INDEX_PAGE、LOB_DATA_PAGE等） |
| PageFreePercent | int | ページ内の空き領域率（0-100） |
| IsAllocated | string | ページが割り当て済みかどうか（'True'/'False'） |
| IsMixedPage | string | 混合ページ割り当てかどうか（'True'/'False'） |

### 出力先

PowerShellパイプライン（System.Data.DataRow）

## 処理フロー

### 処理シーケンス

```
1. SQLクエリの構築（beginブロック）
   └─ sys.dm_db_database_page_allocationsへの基本クエリ
   └─ Schema/Tableパラメータによる条件追加
2. インスタンスごとの処理ループ
   └─ Connect-DbaInstance（MinimumVersion 11）
3. データベースオブジェクトの収集
   └─ SqlInstance指定時: server.Databases取得
   └─ InputObject指定時: パイプラインから受け取り
4. データベースごとのクエリ実行
   └─ バージョン再検証（VersionMajor >= 11）
   └─ db.Query()でページ情報取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ構築]
    B --> C{Schema指定?}
    C -->|Yes| D[WHERE句追加]
    C -->|No| E{Table指定?}
    D --> E
    E -->|Yes| F[AND/WHERE句追加]
    E -->|No| G{インスタンスループ}
    F --> G
    G -->|次のインスタンス| H[Connect-DbaInstance]
    H --> I{MinVersion 11以上?}
    I -->|No| J[エラー出力]
    J --> G
    I -->|Yes| K[DBコレクション取得]
    K --> L{DBループ}
    L -->|次のDB| M{VersionMajor >= 11?}
    M -->|No| N[エラー出力]
    N --> L
    M -->|Yes| O[db.Query実行]
    O --> P[結果出力]
    P --> L
    L -->|完了| G
    G -->|完了| Q[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-701 | 最小バージョン要件 | SQL Server 2012以上が必要（MinimumVersion 11） | 接続時 |
| BR-702 | 動的クエリ構築 | Schema/Tableパラメータに応じてWHERE句を動的構築 | クエリ構築時 |
| BR-703 | DETAILED モード | DMVをDETAILEDモードで呼び出し詳細情報を取得 | 常時 |

### 計算ロジック

特に計算ロジックはなく、DMVからの直接取得。IsAllocated/IsMixedPageはCASE式で'True'/'False'文字列に変換。

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

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

| 操作 | 対象テーブル/ビュー | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ページ情報取得 | sys.dm_db_database_page_allocations | SELECT | ページ割り当て詳細情報 |
| テーブル情報取得 | sys.tables | JOIN | テーブル名取得 |
| スキーマ情報取得 | sys.schemas | JOIN | スキーマ名取得 |

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

#### sys.dm_db_database_page_allocations

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | page_type_desc | ページタイプの説明 | - |
| SELECT | page_free_space_percent | 空き領域率 | - |
| SELECT | is_allocated | 割り当て状態 | - |
| SELECT | is_mixed_page_allocation | 混合ページフラグ | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで処理継続 |
| - | Stop-Function | バージョン要件を満たさない | メッセージ出力して処理継続 |
| - | Stop-Function | クエリ実行エラー | エラー出力して次のDBを処理 |

### リトライ仕様

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

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

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

## パフォーマンス要件

DMVへのクエリは詳細モード（DETAILED）のため、大規模テーブルでは処理時間が長くなる可能性がある。

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

- VIEW DATABASE STATE権限が必要
- SqlCredentialパラメータで代替認証情報をサポート

## 備考

- SQL Server 2012以上が必要
- sys.dm_db_database_page_allocations DMVに依存

---

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

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

### 推奨読解順序

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

SQLクエリの構造と動的構築ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbPageInfo.ps1 | `public/Get-DbaDbPageInfo.ps1` | 99-116行目：SQLクエリ定義 |
| 1-2 | Get-DbaDbPageInfo.ps1 | `public/Get-DbaDbPageInfo.ps1` | 118-128行目：動的WHERE句構築 |

**読解のコツ**: beginブロックでベースクエリを定義し、Schema/Tableパラメータに応じてWHERE句を動的に追加している。

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

パラメータ定義とデータベースコレクションの収集を確認。

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

**主要処理フロー**:
1. **99-128行目**: SQLクエリ構築（beginブロック）
2. **132-139行目**: インスタンス接続（MinimumVersion 11）
3. **141-145行目**: データベースコレクション取得
4. **149-160行目**: クエリ実行とエラーハンドリング

#### Step 3: クエリ実行ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbPageInfo.ps1 | `public/Get-DbaDbPageInfo.ps1` | 151-156行目：バージョン再検証とクエリ実行 |

**主要処理フロー**:
- **136行目**: Connect-DbaInstanceで-MinimumVersion 11を指定
- **152行目**: `$db.Parent.VersionMajor -ge 11`で再検証
- **153行目**: `$db.Query($sql)`でクエリ実行

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

```
Get-DbaDbPageInfo
    │
    ├─ Connect-DbaInstance（-MinimumVersion 11）
    │
    ├─ Stop-Function（エラー処理）
    │
    └─ $db.Query()
           └─ sys.dm_db_database_page_allocations
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance
                      │
                      ▼
               ┌─────────────────┐
Schema ──────▶ │ 動的クエリ構築  │
               │ (WHERE句追加)   │
Table ────────▶│                │
               └────────┬────────┘
                        │
InputObject ────────────┤
                        ▼
               ┌─────────────────┐
               │ dm_db_database_ │
               │ page_allocations│
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐      ┌─ ComputerName
               │ DataRow         │──────┼─ Database
               └─────────────────┘      ├─ Schema
                                        ├─ Table
                                        ├─ PageType
                                        ├─ PageFreePercent
                                        ├─ IsAllocated
                                        └─ IsMixedPage
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbPageInfo.ps1 | `public/Get-DbaDbPageInfo.ps1` | ソース | メイン処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
