# 機能設計書 219-Set-DbaDbIdentity

## 概要

本ドキュメントは、DBCC CHECKIDENTを使用してIDENTITY列の値を確認およびリセットするSet-DbaDbIdentity関数の機能設計書です。

### 本機能の処理概要

Set-DbaDbIdentityは、DBCC CHECKIDENTを実行してIDENTITY列を持つテーブルの現在のID値を確認し、オプションで特定の値に再シードします。これは、バルクデータ操作、インポート、削除の後に、ID値が実際のテーブルデータと同期しなくなる可能性がある場合に不可欠です。ReSeedValueなしで実行すると、現在のID値とIDENTITY列の最大値を報告します。ReSeedValueを指定すると、重複キーエラーを防ぐか、IDギャップを埋めるためにIDカウンターをリセットします。

**業務上の目的・背景**：IDENTITY列は自動的に連番を生成しますが、バルク削除、TRUNCATE TABLE、データインポートなどの操作後にID値とデータが不整合になることがあります。また、テスト環境から本番環境へのデータ移行時にID値のリセットが必要になることもあります。本機能は、IDENTITY値の現状確認と必要に応じた再シードを効率的に行います。

**機能の利用シーン**：
- バルクデータ操作後にIDENTITY値の整合性を確認する場合
- データインポート後にID値をリセットする場合
- 重複キーエラーを防ぐためにID値を調整する場合
- テスト環境のIDカウンターをリセットする場合

**主要な処理内容**：
1. 対象インスタンスへの接続
2. DBCC CHECKIDENTコマンドの構築
3. コマンドの実行と結果の解析
4. 結果のPSCustomObjectとしての出力

**関連システム・外部連携**：
- SQL Server Database Engine
- DBCC CHECKIDENT T-SQLコマンド

**権限による制御**：テーブルに対するALTER権限、またはdb_ddladminまたはdb_ownerロールのメンバーシップが必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIインターフェース | 主画面 | コマンドライン実行 |

## 機能種別

データベース操作 / DBCC / メンテナンス

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可 |
| SqlCredential | PSCredential | No | 認証用資格情報 | PSCredential型 |
| Database | string[] | No | 対象データベース名 | ReSeedValue使用時は単一のみ |
| Table | string[] | No | 対象テーブル名 | ReSeedValue使用時は単一のみ |
| ReSeedValue | int | No | 新しいID値 | 整数値 |
| EnableException | switch | No | 例外を有効化 | スイッチ型 |
| WhatIf | switch | No | 実行シミュレーション | スイッチ型 |
| Confirm | switch | No | 確認プロンプト | スイッチ型 |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| Table | string | テーブル名（schema.table形式） |
| Cmd | string | 実行されたDBCCコマンド |
| IdentityValue | string | 現在のID値（次に割り当てられる値） |
| ColumnValue | string | IDENTITY列の最大値（ReSeedValue使用時は空） |
| Output | string | DBCCコマンドの完全な出力 |

### 出力先

- パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   ├─ ReSeedValue使用時のDatabase/Table必須チェック
   └─ ReSeedValue使用時の単一Database/Tableチェック

2. インスタンスへの接続
   └─ Connect-DbaInstance

3. データベースループ
   └─ 各データベースの処理

4. テーブルループ
   ├─ DBCCコマンド構築
   ├─ コマンド実行
   └─ 結果解析

5. 結果出力
   └─ PSCustomObjectとして出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ReSeedValue指定?}
    B -->|Yes| C{DB & Table指定?}
    C -->|No| D[エラー終了]
    C -->|Yes| E{単一DB & Table?}
    E -->|No| D
    E -->|Yes| F[接続処理]
    B -->|No| F

    F --> G[Connect-DbaInstance]
    G --> H{接続成功?}
    H -->|No| I[エラー、次へ継続]
    H -->|Yes| J[DBフィルタリング]

    J --> K[各DBをループ]
    K --> L{DB accessible?}
    L -->|No| M[スキップ]
    L -->|Yes| N[各テーブルをループ]

    N --> O[DBCCコマンド構築]
    O --> P{ShouldProcess確認}
    P -->|No| Q[スキップ]
    P -->|Yes| R[Invoke-DbaQuery実行]

    R --> S{結果あり?}
    S -->|Yes| T[結果解析]
    S -->|No| U[null値設定]

    T --> V[PSCustomObject出力]
    U --> V
    V --> W{次のテーブル?}
    Q --> W
    W -->|Yes| N
    W -->|No| X{次のDB?}

    M --> X
    X -->|Yes| K
    X -->|No| Y{次のインスタンス?}
    I --> Y
    Y -->|Yes| G
    Y -->|No| Z[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ReSeedValue制約 | 使用時はDatabaseとTable両方が必須 | ReSeedValue指定時 |
| BR-002 | 単一指定制約 | ReSeedValue使用時は単一DB/単一Tableのみ | ReSeedValue指定時 |
| BR-003 | アクセス可能性チェック | IsAccessible=falseのDBはスキップ | 常時 |
| BR-004 | DBCC構文選択 | ReSeedValueの有無でDBCC構文が変わる | 常時 |

### 計算ロジック

```powershell
# DBCC CHECKIDENT構文
# ReSeedValueなし: DBCC CHECKIDENT('テーブル名')
# ReSeedValueあり: DBCC CHECKIDENT('テーブル名', RESEED, 値)

# 結果解析（スペース区切りで分割）
$identityValue = $words[6].Replace("'", "").Replace(",", "")
$columnValue = $words[10].Replace("'", "").Replace(".", "")
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ID値確認 | 指定テーブル | SELECT相当 | 現在のID値と最大値を取得 |
| ID値リセット | 指定テーブル | UPDATE相当 | IDENTITYシード値を更新 |

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

DBCC CHECKIDENTコマンドはシステムメタデータを操作します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータ不足 | ReSeedValue使用時にDB/Table未指定 | エラーメッセージ出力、処理終了 |
| - | 複数指定エラー | ReSeedValue使用時に複数DB/Table | エラーメッセージ出力、処理終了 |
| - | 接続失敗 | SQL Serverへの接続失敗 | 次のインスタンスへ継続 |
| - | DBアクセス不可 | データベースがアクセス不可 | スキップして継続 |
| - | DBCC実行失敗 | DBCC CHECKIDENT実行失敗 | Stop-Functionで継続 |

### リトライ仕様

リトライは行いません。エラー発生時は次の項目へ継続処理します。

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

DBCC CHECKIDENTは暗黙のトランザクションで実行されます。

## パフォーマンス要件

特になし。DBCC CHECKIDENTは軽量なメタデータ操作です。

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

- テーブルに対するALTER権限が必要
- db_ddladminまたはdb_ownerロールでも実行可能
- RESEEDオプションはデータ整合性に影響するため注意が必要

## 備考

- DBCC CHECKIDENTの詳細は[Microsoft Docs](https://docs.microsoft.com/en-us/sql/t-sql/database-console-commands/dbcc-checkident-transact-sql)を参照
- ReSeedValueを指定しない場合、現在のID値と列の最大値のみを報告
- ReSeedValueに0を指定すると、最大値+1にリセット

---

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

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

### 推奨読解順序

#### Step 1: パラメータと検証ロジックを理解する

関数のエントリーポイントと入力検証を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaDbIdentity.ps1 | `public/Set-DbaDbIdentity.ps1` 97-106行目 | パラメータ定義 |

**読解のコツ**: ConfirmImpact='High'が設定されており、破壊的操作として扱われます。

#### Step 2: 入力検証処理を理解する

ReSeedValue使用時の制約チェックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaDbIdentity.ps1 | `public/Set-DbaDbIdentity.ps1` 112-122行目 | ReSeedValue制約チェック |

**主要処理フロー**:
1. **112-116行目**: ReSeedValue使用時のDB/Table必須チェック
2. **118-121行目**: ReSeedValue使用時の単一DB/Tableチェック

#### Step 3: DBCCコマンド構築と実行を理解する

DBCC CHECKIDENTコマンドの構築と実行を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbIdentity.ps1 | `public/Set-DbaDbIdentity.ps1` 107-110, 145-156行目 | コマンド構築、実行 |

**主要処理フロー**:
- **107-109行目**: StringBuilderでコマンドテンプレート構築
- **147-152行目**: ReSeedValueの有無でコマンド構文を切り替え
- **156行目**: Invoke-DbaQuery -MessagesToOutput で実行

#### Step 4: 結果解析と出力を理解する

DBCCコマンドの結果解析と出力を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaDbIdentity.ps1 | `public/Set-DbaDbIdentity.ps1` 157-186行目 | 結果解析、PSCustomObject出力 |

**主要処理フロー**:
- **158-164行目**: 結果文字列のスペース分割と値抽出
- **175-186行目**: PSCustomObject出力（IdentityValue, ColumnValue含む）

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

```
Set-DbaDbIdentity
    │
    ├─ Test-Bound (パラメータ指定確認)
    │
    ├─ Connect-DbaInstance (SQL Server接続)
    │
    ├─ System.Text.StringBuilder (コマンド構築)
    │
    ├─ Invoke-DbaQuery (DBCC実行)
    │      └─ -MessagesToOutput (メッセージ取得)
    │
    └─ Stop-Function (エラー処理)
```

### データフロー図

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

SqlInstance        ───▶ Connect-DbaInstance   ───▶
     +                        │
Database                      ▼
     +             ───▶ DBCCコマンド構築       ───▶
Table                         │
     +                        ▼
ReSeedValue        ───▶ Invoke-DbaQuery        ───▶
                              │
                              ▼
               ───▶ 結果解析              ───▶ PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaDbIdentity.ps1 | `public/Set-DbaDbIdentity.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行 |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータ指定確認 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
