# 画面設計書 178-ID使用量

## 概要

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

### 本画面の処理概要

本コマンドは、データベース内のIDENTITY列のシード消費状況を分析し、利用可能な範囲の使用率を計算します。

**業務上の目的・背景**：IDENTITY列には各データ型（tinyint、smallint、int、bigint）に基づく最大値制限があります。この制限に達すると新しいレコードの挿入が失敗し、アプリケーション障害が発生します。本コマンドを使用することで、DBAは事前にIDENTITY列の枯渇状況を監視し、再シーディングやデータ型変更などの対策を計画できます。

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

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスに接続（SQL Server 2008以上が必要）
2. 各データベースに対してsys.identity_columns、sys.objects、sys.typesをジョインしてクエリ
3. 各データ型の最大値（tinyint: 255、smallint: 32767、int: 2147483647、bigint: 9223372036854775807）に基づいて使用率を計算
4. Thresholdパラメータで指定された閾値以上の結果のみフィルタリング
5. 結果をPercentUsedの降順でソートして出力

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

**権限による表示制御**：sys.identity_columns、sys.objects、sys.typesへのVIEW DEFINITION権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 248 | Test-DbaIdentityUsage | 主機能 | ID列使用量のテスト |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド: `Test-DbaIdentityUsage`

## 入出力項目

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証用資格情報 |
| Database | object[] | No | 対象データベース |
| ExcludeDatabase | object[] | No | 除外データベース |
| Threshold | int | No | 最小使用率閾値（デフォルト: 0） |
| ExcludeSystem | switch | No | システムデータベースを除外 |
| EnableException | switch | No | 例外処理モードの有効化 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|---|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| Schema | string | スキーマ名 |
| Table | string | テーブル名 |
| Column | string | IDENTITY列名 |
| SeedValue | bigint | 初期シード値 |
| IncrementValue | bigint | 増分値 |
| LastValue | bigint | 最後に割り当てられたID値 |
| MaxNumberRows | bigint | データ型で可能な最大行数（デフォルト非表示） |
| NumberOfUses | bigint | ID値の使用回数（デフォルト非表示） |
| PercentUsed | decimal | 利用可能範囲の使用率（0-100、小数点2桁） |

## イベント仕様

### 1-コマンド実行

1. SqlInstanceパラメータを検証
2. 指定されたインスタンスに接続（MinimumVersion 10 = SQL Server 2008以上）
3. Database/ExcludeDatabase/ExcludeSystemパラメータでフィルタリング
4. 各データベースのアクセス可能性を確認
5. CTE（共通テーブル式）を使用した複雑なSQLクエリを実行
6. 各データ型の最大値に基づいて使用率を計算
7. Threshold以上の結果をPercentUsed降順でソート
8. PSCustomObjectを生成しパイプラインに出力（MaxNumberRows、NumberOfUsesはデフォルト非表示）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行 | sys.identity_columns | SELECT | IDENTITY列情報の取得 |
| コマンド実行 | sys.objects | SELECT | オブジェクト情報の取得 |
| コマンド実行 | sys.types | SELECT | データ型情報の取得 |

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

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

## メッセージ仕様

| メッセージID | 種別 | 条件 | メッセージ内容 |
|-------------|------|------|--------------|
| M001 | Error | 接続失敗 | "Failure" |
| M002 | Verbose | データベース処理中 | "Processing {db} on {instance}" |
| M003 | Warning | データベースアクセス不可 | "The database {db} is not accessible. Skipping." |
| M004 | Error | データ取得エラー | "Error capturing data on {db}" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラーを出力し、次のインスタンスに継続 |
| SQL Server 2008未満 | Connect-DbaInstanceのMinimumVersionで接続拒否 |
| データベースアクセス不可 | Stop-Functionでエラーを出力し、次のデータベースに継続 |
| クエリ実行エラー | Stop-Functionでエラーを出力し、次のデータベースに継続 |

## 備考

- 各データ型の最大値：
  - tinyint: 0 - 255
  - smallint: -32768 - 32767
  - int: -2147483648 - 2147483647
  - bigint: -9223372036854775808 - 9223372036854775807
- PercentUsedがNULLの行は出力されません
- 結果はPercentUsedの降順でソートされます

---

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

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

### 推奨読解順序

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

出力オブジェクトのプロパティ構成とデフォルト表示を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaIdentityUsage.ps1 | `public/Test-DbaIdentityUsage.ps1` | 207-222行目：出力オブジェクトのプロパティ定義 |

**読解のコツ**: `Select-DefaultView -Exclude MaxNumberRows, NumberOfUses` でデフォルト表示から除外されているプロパティがあります。

#### Step 2: SQLクエリを理解する

CTE（共通テーブル式）を使用した複雑なクエリ構造を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaIdentityUsage.ps1 | `public/Test-DbaIdentityUsage.ps1` | 99-157行目：SQLクエリ定義 |

**主要処理フロー**:
1. **99-104行目**: CT_DT CTE - 各データ型の最小値・最大値を定義
2. **105-148行目**: CTE_1 - IDENTITY列情報とNumberOfUses、MaxNumberRowsを計算
3. **149-155行目**: CTE_2 - PercentUsedを計算
4. **156-157行目**: 最終SELECT文

#### Step 3: Threshold処理を理解する

閾値パラメータによるフィルタリングを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaIdentityUsage.ps1 | `public/Test-DbaIdentityUsage.ps1` | 159-163行目：WHERE句追加 |

**主要処理フロー**:
- **159-161行目**: Threshold > 0 の場合、WHERE PercentUsed >= {Threshold} を追加
- **206行目**: 結果側でも再度 $row.PercentUsed >= $threshold でフィルタリング

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

```
Test-DbaIdentityUsage
    |
    +-- begin (SQLクエリ定義)
    |
    +-- process
           |
           +-- Connect-DbaInstance (MinimumVersion=10)
           |
           +-- データベースフィルタリング
           |      (Database/ExcludeDatabase/ExcludeSystem)
           |
           +-- foreach ($db in $dbs)
                  |
                  +-- IsAccessible チェック
                  |
                  +-- $db.Query($sql)
                  |
                  +-- foreach ($row in $results)
                         |
                         +-- PercentUsed != DBNull チェック
                         |
                         +-- Threshold フィルタリング
                         |
                         +-- PSCustomObject
                         |
                         +-- Select-DefaultView
```

### データフロー図

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

SqlInstance   ---> Connect-DbaInstance ---> $server
                        |
                        v
               フィルタリング
               (Database/ExcludeDatabase/ExcludeSystem)
                        |
                        v
                   $db.Query($sql)
                   (CTE使用)
                        |
                        v
               PercentUsed計算
               (使用値 / 最大値 * 100)
                        |
                        v
               Threshold フィルタリング
                        |
                        v
               PSCustomObject        ---> パイプライン出力
               + Select-DefaultView       (デフォルト表示項目)
```

### 関連ファイル一覧

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