# 機能設計書 248-Test-DbaIdentityUsage

## 概要

本ドキュメントは、IDENTITYカラムのシード消費を分析し、使用可能な範囲の使用率を計算する機能 `Test-DbaIdentityUsage` の設計仕様を記載する。

### 本機能の処理概要

この機能は、データベース全体のIDENTITYカラムをスキャンし、データ型の上限（tinyint、smallint、int、bigint）に基づいて、使用可能なシード範囲のどれだけが消費されたかを計算する。これにより、DBAsはテーブルが最大値に達してアプリケーション障害を引き起こす前に、ID枯渇が近づいているテーブルを事前に特定できる。

**業務上の目的・背景**：IDENTITYカラムが最大値に達すると、新しい行の挿入ができなくなり、アプリケーションエラーの原因となる。本機能により、再シードやデータ型変更などの対策を問題発生前に計画できる。

**機能の利用シーン**：
- 定期的なID使用率監視
- 容量計画とキャパシティプランニング
- 運用監視ダッシュボードへのデータ提供
- データベースメンテナンス計画の立案

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスに接続（SQL Server 2008以上）
2. アクセス可能なデータベースを取得
3. 各データベースでIDENTITYカラム情報を収集
4. データ型に基づく最大値と現在値から使用率を計算
5. しきい値以上の結果を出力

**関連システム・外部連携**：sys.identity_columns、sys.objects、sys.typesシステムビュー。

**権限による制御**：データベースへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 画面機能マッピングに該当なし |

## 機能種別

診断処理 / 監視処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | ターゲットSQL Serverインスタンス | SQL Server 2008以上 |
| SqlCredential | PSCredential | No | 代替資格情報 | 有効なPowerShell資格情報 |
| Database | object[] | No | チェック対象データベース | - |
| ExcludeDatabase | object[] | No | 除外するデータベース | - |
| Threshold | int | No | 最小使用率% | デフォルト 0 |
| ExcludeSystem | switch | No | システムデータベースを除外 | - |
| EnableException | switch | No | 例外のスロー有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（computer\instance形式） |
| Database | string | テーブルが存在するデータベース名 |
| Schema | string | テーブルが存在するスキーマ名 |
| Table | string | IDENTITYカラムを持つテーブル名 |
| Column | string | IDENTITYプロパティを持つカラム名 |
| SeedValue | bigint | IDENTITYカラムの初期シード値 |
| IncrementValue | bigint | IDENTITY生成のインクリメント値 |
| LastValue | bigint | 最後に割り当てられたIDENTITY値 |
| MaxNumberRows | bigint | データ型で可能な最大行数 |
| NumberOfUses | bigint | IDENTITY値の使用回数 |
| PercentUsed | numeric(18,2) | データ型上限に対する使用済みシード範囲の割合 |

### 出力先

- PowerShellパイプライン出力（PSCustomObject）
- デフォルト表示ではMaxNumberRowsとNumberOfUsesは除外

## 処理フロー

### 処理シーケンス

```
1. beginブロックでSQLクエリ構築
   └─ CTEを使用したIDENTITY使用率計算クエリ
   └─ Thresholdによるフィルタリング条件追加
2. processブロックで各インスタンス処理
   └─ Connect-DbaInstance（MinimumVersion 10）で接続
   └─ データベースリスト取得とフィルタリング
3. 各データベースに対してクエリ実行
   └─ アクセス可能性確認
   └─ SQLクエリ実行
4. 結果の出力
   └─ PercentUsedがしきい値以上の行のみ出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ構築]
    B --> C{Threshold > 0?}
    C -->|Yes| D[WHERE句追加]
    C -->|No| E[ORDER BY句追加]
    D --> F{各インスタンスをループ}
    E --> F
    F --> G[Connect-DbaInstance MinimumVersion 10]
    G --> H{接続成功?}
    H -->|No| I[Stop-Function]
    I --> F
    H -->|Yes| J[データベース取得]
    J --> K[フィルタリング適用]
    K --> L{各DBをループ}
    L --> M{アクセス可能?}
    M -->|No| N[Stop-Function]
    N --> L
    M -->|Yes| O[SQLクエリ実行]
    O --> P{各行をループ}
    P --> Q{PercentUsed有効?}
    Q -->|No| P
    Q -->|Yes| R{>= Threshold?}
    R -->|Yes| S[結果出力]
    R -->|No| P
    S --> P
    P -->|完了| L
    L -->|完了| F
    F -->|完了| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-248-1 | データ型上限 | tinyint=255, smallint=32767, int=2147483647, bigint=9223372036854775807 | 常時 |
| BR-248-2 | 使用率計算 | (NumberOfUses / MaxNumberRows) * 100 | 各IDENTITYカラム |
| BR-248-3 | しきい値フィルタ | PercentUsed >= Threshold の行のみ出力 | Threshold指定時 |
| BR-248-4 | インクリメント考慮 | 負のインクリメント値も考慮した計算 | increment_value < 0 の場合 |

### データ型上限定義

| データ型 | 最小値 | 最大値 |
|---------|--------|--------|
| tinyint | 0 | 255 |
| smallint | -32768 | 32767 |
| int | -2147483648 | 2147483647 |
| bigint | -9223372036854775808 | 9223372036854775807 |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| IDENTITY情報取得 | sys.identity_columns | SELECT | IDENTITYカラムの情報取得 |
| オブジェクト情報取得 | sys.objects | SELECT | テーブル名とスキーマ取得 |
| 型情報取得 | sys.types | SELECT | データ型名取得 |

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

#### sys.identity_columns

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, seed_value, increment_value, last_value | seed_value IS NOT NULL | シード値がnullでないもの |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスへの接続失敗 | Stop-Functionで処理継続 |
| AccessError | アクセスエラー | データベースにアクセス不可 | Stop-Functionで処理継続 |
| QueryError | クエリエラー | SQLクエリ実行失敗 | Stop-Functionで処理継続 |

### リトライ仕様

リトライ処理なし。各インスタンス/データベースに対してContinueでループを継続。

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

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

## パフォーマンス要件

- CTE（共通テーブル式）を使用した効率的なクエリ
- データベース数とIDENTITYカラム数に応じて処理時間が増加

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

- SQL Server認証、Windows認証、Active Directory認証をサポート
- システムビューへのアクセス権限が必要
- MFAサポートが必要な場合はConnect-DbaInstanceの事前使用を推奨

## 備考

- SQL Server 2008以上が必要（MinimumVersion 10）
- PercentUsedがDBNull::Valueの場合はスキップ
- 結果は使用率降順でソート

---

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

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

### 推奨読解順序

#### Step 1: コマンド構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaIdentityUsage.ps1 | `public/Test-DbaIdentityUsage.ps1` | パラメータ定義、コメントベースヘルプ |

**読解のコツ**: Select-DefaultViewでの表示項目制御に注目。

#### Step 2: beginブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaIdentityUsage.ps1 | `public/Test-DbaIdentityUsage.ps1` | SQLクエリの構造（CTE使用） |

**主要処理フロー**:
1. **99-157行目**: CTEを使用したSQLクエリ構築
2. **159-163行目**: Thresholdによるフィルタリング条件追加

#### Step 3: processブロックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaIdentityUsage.ps1 | `public/Test-DbaIdentityUsage.ps1` | データベースループと結果処理 |

**主要処理フロー**:
1. **167-172行目**: インスタンスへの接続
2. **174-186行目**: データベースフィルタリング
3. **188-199行目**: クエリ実行
4. **201-222行目**: 結果出力（PercentUsed検証含む）

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

```
Test-DbaIdentityUsage
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server SMO接続（MinimumVersion 10）
    │
    ├─ $server.Databases
    │      └─ データベースリスト取得
    │
    ├─ $db.Query($sql)
    │      ├─ sys.identity_columns
    │      ├─ sys.objects
    │      └─ sys.types
    │
    └─ Select-DefaultView
           └─ 出力プロパティフィルタリング（MaxNumberRows, NumberOfUses除外）
```

### データフロー図

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

SqlInstance    ───▶ Connect-DbaInstance ───▶ $server
                           │
Threshold      ───▶ SQLクエリ構築 ───▶ WHERE句条件
                           │
                           ▼
                    $server.Databases ───▶ $dbs
                           │
                           ▼
                    フィルタリング ───▶ 対象DBリスト
                           │
                           ▼
                    $db.Query($sql) ───▶ IDENTITY情報
                           │
                           ▼
                    使用率計算 ───▶ PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaIdentityUsage.ps1 | `public/Test-DbaIdentityUsage.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Get-DbaDbIdentity.ps1 | `public/Get-DbaDbIdentity.ps1` | ソース | IDENTITY値取得（関連） |
| Set-DbaDbIdentity.ps1 | `public/Set-DbaDbIdentity.ps1` | ソース | IDENTITY値設定（関連） |
