# 機能設計書 52-Get-DbaDbCompression

## 概要

本ドキュメントは、SQL Serverデータベースのテーブルとインデックスの圧縮設定を取得する機能「Get-DbaDbCompression」の設計仕様を記述する。

### 本機能の処理概要

Get-DbaDbCompressionは、SQL Serverデータベース内のテーブルおよびインデックスの現在の圧縮設定、サイズ、行数を取得し、圧縮最適化の分析に必要な情報を提供する機能である。

**業務上の目的・背景**：SQL Serverのデータ圧縮機能は、ストレージコストの削減とI/Oパフォーマンスの向上に効果的だが、現在の圧縮状態を把握しなければ最適化の方針を立てることができない。本機能は、テーブルやインデックスごとの圧縮タイプ（None/Row/Page/Columnstore）、使用領域、行数を一覧化し、圧縮候補の特定やコンプライアンスレポートの作成を支援する。

**機能の利用シーン**：
- データベースの圧縮状態の棚卸し・監査
- 圧縮適用前の現状分析
- ストレージ使用量レポートの作成
- 圧縮最適化プロジェクトの事前調査

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続
2. アクセス可能な非システムデータベースを列挙
3. 各データベースのテーブルを走査
4. ヒープ、クラスタ化インデックス、非クラスタ化インデックスの各パーティションの圧縮情報を取得
5. 結果をPSCustomObjectとして出力

**関連システム・外部連携**：
- SMO (SQL Server Management Objects)を使用したテーブル・インデックス情報取得

**権限による制御**：
- データベースへの読み取りアクセス権限が必要
- sys.partitionsおよびテーブルメタデータへのアクセス権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主画面 | PowerShellコマンドラインからの直接実行 |

## 機能種別

データ取得 / レポート生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | SQL Server接続用認証情報 | - |
| Database | string[] | No | 対象データベース名 | - |
| ExcludeDatabase | string[] | No | 除外データベース名 | - |
| Table | string[] | No | 対象テーブル名 | - |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- SMO: Server.Databases コレクション
- SMO: Database.Tables コレクション
- SMO: Table.PhysicalPartitions / Index.PhysicalPartitions

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| DatabaseId | int | データベースID |
| Schema | string | スキーマ名 |
| TableName | string | テーブル名 |
| IndexName | string | インデックス名（ヒープの場合はnull） |
| Partition | int | パーティション番号 |
| IndexID | int | インデックスID（ヒープは0） |
| IndexType | string | インデックスタイプ（Heap/ClusteredIndex/NonClusteredIndex等） |
| DataCompression | string | 圧縮タイプ（None/Row/Page/ColumnStore） |
| SizeCurrent | dbasize | 現在のサイズ（バイト） |
| RowCount | bigint | 行数 |

### 出力先

PowerShellパイプライン（即座に出力）

## 処理フロー

### 処理シーケンス

```
1. SQL Serverインスタンスに接続
   └─ Connect-DbaInstance -MinimumVersion 10 (SQL Server 2008以上)

2. データベース一覧取得
   └─ IsAccessible かつ IsSystemObject = false のデータベースをフィルタ

3. Database/ExcludeDatabaseパラメータでフィルタ
   └─ 指定されたデータベースのみ処理

4. 各データベースのテーブル走査
   └─ Tableパラメータ指定時はテーブル名でフィルタ

5. ヒープパーティション情報取得
   └─ HasHeapIndex = true のテーブルのPhysicalPartitionsを処理

6. インデックスパーティション情報取得
   └─ 各テーブルのIndexesコレクションのPhysicalPartitionsを処理

7. 結果出力
   └─ PSCustomObjectとして即座にパイプラインへ出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function]
    D --> A
    C -->|Yes| E[データベース一覧取得]
    E --> F[Database/ExcludeDatabaseフィルタ]
    F --> G[データベースループ開始]
    G --> H[テーブル一覧取得]
    H --> I[Tableフィルタ]
    I --> J[テーブルループ開始]
    J --> K{HasHeapIndex?}
    K -->|Yes| L[ヒープパーティション出力]
    L --> M[インデックスループ]
    K -->|No| M
    M --> N[インデックスパーティション出力]
    N --> O{次のテーブル?}
    O -->|Yes| J
    O -->|No| P{次のデータベース?}
    P -->|Yes| G
    P -->|No| Q{次のインスタンス?}
    Q -->|Yes| A
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | システムDB除外 | システムデータベースは対象外 | 常時 |
| BR-02 | アクセス可能DB限定 | IsAccessible = true のDBのみ処理 | 常時 |
| BR-03 | 最小バージョン | SQL Server 2008以上が必要 | 常時 |

### 計算ロジック

- SizeCurrent（ヒープ/クラスタ化インデックス）: Table.DataSpaceUsed * 1024 バイト
- SizeCurrent（非クラスタ化インデックス）: Index.SpaceUsed * 1024 バイト

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 圧縮情報取得 | sys.partitions, sys.indexes等 | SELECT | SMO経由で間接的に参照 |

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

#### sys.partitions (SMO経由)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | data_compression_desc, rows | SMO PhysicalPartitions経由 | 読み取り専用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverに接続できない | Stop-Functionで処理継続 |
| DatabaseAccessError | データベースアクセスエラー | データベース一覧取得失敗 | Stop-Functionで処理継続 |
| TableQueryError | テーブルクエリエラー | テーブル情報取得失敗 | Stop-Functionで処理継続 |

### リトライ仕様

特になし。各インスタンス/データベースは独立して処理され、失敗時は次へ継続する。

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

読み取り専用操作のためトランザクション制御なし。

## パフォーマンス要件

大規模データベースでは多数のテーブル・インデックスを走査するため、処理時間が長くなる可能性がある。Tableパラメータで対象を絞ることで高速化可能。

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

- SqlCredentialによる認証情報の安全な受け渡し
- データベースメタデータの読み取りのみ（書き込みなし）

## 備考

- dbasizeオブジェクトはB、KB、MB、GB、TB単位で表示可能
- パーティションテーブルでは各パーティションごとに結果が出力される

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbCompression.ps1 | `public/Get-DbaDbCompression.ps1` | 133-148行目（ヒープ出力）、154-170行目（インデックス出力） |

**読解のコツ**: ヒープとインデックスで出力構造は同一だが、IndexNameとIndexIDの値が異なる。ヒープはIndexID=0、IndexName=null。

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

パラメータ定義とprocess block開始を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbCompression.ps1 | `public/Get-DbaDbCompression.ps1` | 89-98行目（パラメータ定義） |

**主要処理フロー**:
1. **101-106行目**: Connect-DbaInstance -MinimumVersion 10
2. **108-117行目**: データベースフィルタリング
3. **122-128行目**: テーブルフィルタリング

#### Step 3: ヒープ処理を理解する

HasHeapIndexプロパティによる分岐を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbCompression.ps1 | `public/Get-DbaDbCompression.ps1` | 131-150行目 |

**主要処理フロー**:
- **131行目**: HasHeapIndex判定
- **132行目**: PhysicalPartitionsループ
- **146行目**: SizeCurrent計算 (DataSpaceUsed * 1024)

#### Step 4: インデックス処理を理解する

各テーブルのインデックスコレクション走査を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDbCompression.ps1 | `public/Get-DbaDbCompression.ps1` | 152-171行目 |

**主要処理フロー**:
- **152行目**: Indexesコレクションループ
- **153行目**: 各インデックスのPhysicalPartitionsループ
- **167行目**: クラスタ化/非クラスタ化でSizeCurrent計算が異なる

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

```
Get-DbaDbCompression
    │
    ├─ Connect-DbaInstance (SQL Server接続)
    │
    └─ [foreach: SqlInstance]
           │
           ├─ Server.Databases (データベース一覧取得)
           │      └─ IsAccessible, IsSystemObject フィルタ
           │
           └─ [foreach: Database]
                  │
                  ├─ Database.Tables (テーブル一覧取得)
                  │
                  └─ [foreach: Table]
                         │
                         ├─ Table.PhysicalPartitions (ヒープ)
                         │      └─ PSCustomObject出力
                         │
                         └─ Table.Indexes
                                └─ [foreach: Index]
                                       │
                                       └─ Index.PhysicalPartitions
                                              └─ PSCustomObject出力
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance
                              │
                              ▼
                       Server.Databases
                              │
                              ▼
Database/ExcludeDB ───▶ フィルタリング
                              │
                              ▼
Table ────────────────▶ テーブルフィルタ
                              │
                              ▼
                       PhysicalPartitions走査
                              │
                              ▼
                       PSCustomObject ─────────────────▶ パイプライン
                       (ComputerName,
                        Database,
                        TableName,
                        DataCompression,
                        SizeCurrent,
                        RowCount 等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbCompression.ps1 | `public/Get-DbaDbCompression.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Set-DbaDbCompression.ps1 | `public/Set-DbaDbCompression.ps1` | ソース | 関連機能（圧縮適用） |
| Test-DbaDbCompression.ps1 | `public/Test-DbaDbCompression.ps1` | ソース | 関連機能（圧縮推奨分析） |
