# 機能設計書 105-Get-DbaDbIdentity

## 概要

本ドキュメントは、テーブルの現在のID値をリシードなしで取得するGet-DbaDbIdentity機能の設計仕様を定義する。

### 本機能の処理概要

本機能は、DBCC CHECKIDENTコマンドをNORESEEDオプション付きで実行し、指定されたテーブルの現在のIDシード値と実際の列の最大値を取得する。テーブルのデータを変更することなく、ID列の状態を安全に確認できる。

**業務上の目的・背景**：ID列のギャップ（欠番）のトラブルシューティング、バルク操作の計画、メンテナンスタスク前のID列使用状況の監査などにおいて、現在のID値を確認する必要がある。本機能により、複数のテーブル、データベース、インスタンスにわたって同時にID列の状態を確認できる。

**機能の利用シーン**：
- ID列のギャップ（欠番）調査
- バルクインサート前のID値確認
- データベースメンテナンス計画
- ID列の監査とレポート作成
- ID列のリシード要否判断

**主要な処理内容**：
1. DBCC CHECKIDENT('テーブル名', NORESEED)コマンドの構築
2. 指定されたテーブルごとにコマンドを実行
3. DBCC出力メッセージの解析
4. ID値と列の最大値を構造化された形式で出力

**関連システム・外部連携**：SQL ServerのDBCC CHECKIDENTコマンドを使用。

**権限による制御**：テーブル所有者またはsysadmin/db_owner/db_ddladminロールのメンバーシップが必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | DBCCコマンド関連画面からの呼び出し（直接の画面関連なし） |

## 機能種別

データ取得・診断処理（DBCCコマンド）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | パイプライン入力対応、Mandatory |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証、AD統合認証 |
| Database | string[] | No | 対象データベース名 | 存在するデータベース名 |
| Table | string[] | No | 対象テーブル名（スキーマ修飾可） | 'Schema.Table'形式 |
| EnableException | switch | No | 例外処理モードの切り替え | - |

### 入力データソース

- SqlInstance: コマンドラインパラメータまたはパイプライン入力
- Table: コマンドラインパラメータ（必須）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（サービス名） |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | テーブルを含むデータベース名 |
| Table | string | チェック対象のテーブル名（スキーマ修飾） |
| Cmd | string | 実行されたDBCC CHECKIDENTコマンド |
| IdentityValue | string/null | 現在のIDシード値（取得不可の場合null） |
| ColumnValue | string/null | ID列の最大値（取得不可の場合null） |
| Output | string | DBCCコマンドの生の出力メッセージ |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. コマンドテンプレートの初期化
   └─ "DBCC CHECKIDENT(#options#, NORESEED)"
2. パラメータ検証
   └─ Tableパラメータの必須チェック
3. インスタンスごとの処理ループ
   └─ Connect-DbaInstanceで接続
4. データベースごとの処理ループ
   └─ アクセシビリティチェック
5. テーブルごとのDBCCコマンド実行
   └─ クエリ構築とShouldProcess確認
   └─ Invoke-DbaQueryでMessagesToOutput
6. 結果の解析と出力
   └─ 出力メッセージからID値を抽出
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[コマンドテンプレート初期化]
    B --> C{Table指定あり?}
    C -->|No| D[エラー出力・終了]
    C -->|Yes| E{インスタンスループ}
    E -->|次のインスタンス| F[Connect-DbaInstance]
    F --> G{接続成功?}
    G -->|No| H[エラー出力]
    H --> E
    G -->|Yes| I{データベースループ}
    I -->|次のDB| J{IsAccessible?}
    J -->|No| K[エラー出力・スキップ]
    K --> I
    J -->|Yes| L{テーブルループ}
    L -->|次のテーブル| M[クエリ構築]
    M --> N{ShouldProcess?}
    N -->|No| L
    N -->|Yes| O[DBCC CHECKIDENT実行]
    O --> P{実行成功?}
    P -->|No| Q[エラー出力]
    Q --> L
    P -->|Yes| R[出力解析]
    R --> S[PSCustomObject生成]
    S --> L
    L -->|完了| I
    I -->|完了| E
    E -->|完了| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-501 | Tableパラメータ必須 | Tableパラメータを指定しないとエラー終了 | 処理開始時 |
| BR-502 | NORESEED使用 | ID値の変更を行わない安全な読み取り専用操作 | 常時 |
| BR-503 | ShouldProcess対応 | WhatIf/Confirmパラメータに対応 | コマンド実行時 |

### 計算ロジック

**出力メッセージの解析**：
- DBCC CHECKIDENT出力: `Checking identity information: current identity value '10', current column value '8'.`
- 出力をスペースで分割し、6番目の単語（IdentityValue）と10番目の単語（ColumnValue）を抽出
- クォートとカンマを除去

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ID値取得 | 指定テーブル | DBCC | DBCC CHECKIDENT(NORESEED)でID情報を読み取り |

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

DBCC CHECKIDENTはシステムカタログを参照してID列の情報を取得。NORESEEDオプションにより、データ変更は発生しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | Tableパラメータ未指定 | エラーメッセージ出力して終了 |
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで処理継続 |
| - | Stop-Function | データベースがアクセス不可 | スキップして次のDBを処理 |
| - | Stop-Function | DBCC実行エラー | エラー出力して次のテーブルを処理 |

### リトライ仕様

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

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

NORESEEDオプションにより読み取り専用操作。トランザクション管理は不要。

## パフォーマンス要件

DBCC CHECKIDENTは軽量な操作で、即座に完了。

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

- テーブル所有者またはsysadmin/db_owner/db_ddladminロールが必要
- SqlCredentialパラメータで代替認証情報をサポート
- SupportsShouldProcessでWhatIf/Confirmをサポート

## 備考

- 関連コマンド：Reset-DbaIdentity（ID値のリセット）
- Microsoftドキュメント参照: https://docs.microsoft.com/en-us/sql/t-sql/database-console-commands/dbcc-checkident-transact-sql

---

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

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

### 推奨読解順序

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

コマンドテンプレートと出力オブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbIdentity.ps1 | `public/Get-DbaDbIdentity.ps1` | 99-101行目：StringBuilderによるコマンドテンプレート |
| 1-2 | Get-DbaDbIdentity.ps1 | `public/Get-DbaDbIdentity.ps1` | 150-160行目：出力オブジェクト構造 |

**読解のコツ**: StringBuilderを使用してDBCCコマンドのテンプレートを構築。#options#プレースホルダーをテーブル名で置換している。

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

パラメータ定義とShouldProcess対応を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbIdentity.ps1 | `public/Get-DbaDbIdentity.ps1` | 90-98行目：パラメータ定義 |
| 2-2 | Get-DbaDbIdentity.ps1 | `public/Get-DbaDbIdentity.ps1` | 90行目：CmdletBinding(SupportsShouldProcess) |

**主要処理フロー**:
1. **99-101行目**: コマンドテンプレート初期化（beginブロック）
2. **104-107行目**: Tableパラメータ必須チェック
3. **108-114行目**: インスタンス接続
4. **122-127行目**: データベースアクセシビリティチェック
5. **129-145行目**: テーブルループとDBCC実行

#### Step 3: 出力解析ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbIdentity.ps1 | `public/Get-DbaDbIdentity.ps1` | 137-144行目：出力メッセージ解析 |

**主要処理フロー**:
- **136行目**: Invoke-DbaQueryで-MessagesToOutputオプション使用
- **138行目**: $results.Split(" ")でスペース区切り
- **139行目**: $words[6]からIdentityValue抽出（クォート・カンマ除去）
- **140行目**: $words[10]からColumnValue抽出（クォート・ピリオド除去）

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

```
Get-DbaDbIdentity
    │
    ├─ Test-Bound（パラメータ検証）
    │
    ├─ Stop-Function（エラー処理）
    │
    ├─ Connect-DbaInstance
    │
    ├─ Write-Message（ログ出力）
    │
    ├─ Invoke-DbaQuery（-MessagesToOutput）
    │      └─ DBCC CHECKIDENT実行
    │
    └─ $Pscmdlet.ShouldProcess（WhatIf/Confirm）
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance
                      │
Database ─────────────┤
                      ▼
                ┌─────────────────┐
Table ────────▶ │ クエリ構築      │
                │ DBCC CHECKIDENT │
                │ (NORESEED)      │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐
                │ 出力解析        │
                │ Split(" ")     │
                └────────┬────────┘
                         │
                         ▼
                ┌─────────────────┐      ┌─ ComputerName
                │ PSCustomObject  │──────┼─ Database
                └─────────────────┘      ├─ Table
                                         ├─ Cmd
                                         ├─ IdentityValue
                                         ├─ ColumnValue
                                         └─ Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbIdentity.ps1 | `public/Get-DbaDbIdentity.ps1` | ソース | メイン処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行 |
