# 画面設計書 61-DBCCコマンド

## 概要

本ドキュメントは、dbatools PowerShell モジュールにおける DBCC（Database Console Command）関連コマンドの設計仕様を定義する。SQL Server のデータベース管理コンソールコマンドをPowerShell から実行し、データベースの整合性チェック、メモリ管理、キャッシュクリア、統計情報取得などを行う機能群である。

### 本画面の処理概要

本機能群は、SQL Server の DBCC コマンドを PowerShell から実行するためのラッパーコマンドを提供する。従来は SQL Server Management Studio や sqlcmd で個別に実行する必要があった DBCC コマンドを、PowerShell のパイプライン処理や複数インスタンス一括処理と組み合わせて効率的に実行できる。

**業務上の目的・背景**：DBA（データベース管理者）は、日常的なデータベース保守作業として制約整合性のチェック、ディスク領域の回収、ページ・行カウントの更新、メモリキャッシュの管理などを行う必要がある。これらの操作は SQL Server の DBCC コマンドで実行可能だが、複数のインスタンスやデータベースに対して一括実行するには手間がかかる。本機能群は、これらの DBCC コマンドを PowerShell コマンドレットとして提供し、自動化スクリプトへの組み込みや複数環境への一括適用を容易にする。

**画面へのアクセス方法**：本機能は CLI（コマンドラインインターフェース）として提供される。PowerShell コンソールまたはスクリプトから各コマンドを直接呼び出す。Connect-DbaInstance で接続を確立した後、または SqlInstance パラメータを直接指定して実行する。

**主要な操作・処理内容**：
1. `Invoke-DbaDbDbccCheckConstraint` - データベースの CHECK、FOREIGN KEY 等の制約違反をチェック
2. `Invoke-DbaDbDbccCleanTable` - 可変長列削除後のディスク領域を回収
3. `Invoke-DbaDbDbccUpdateUsage` - カタログビューのページ・行カウント不整合を修正
4. `Get-DbaDbDbccOpenTran` - 最も古いアクティブトランザクションを特定
5. `Invoke-DbaDbccDropCleanBuffer` - バッファプールキャッシュをクリア
6. `Invoke-DbaDbccFreeCache` - プロシージャキャッシュ、セッションキャッシュ、システムキャッシュをクリア
7. `Get-DbaDbccHelp` - DBCC コマンドの構文ヘルプを取得
8. `Get-DbaDbccMemoryStatus` - メモリ使用状況を構造化データで取得
9. `Get-DbaDbccProcCache` - プランキャッシュメモリ使用統計を取得
10. `Get-DbaDbccSessionBuffer` - セッションの入出力バッファを取得
11. `Get-DbaDbccStatistic` - テーブル・インデックスの統計情報を詳細取得

**画面遷移**：PowerShell コマンドは独立して実行されるが、典型的には以下の流れで使用する。
- Connect-DbaInstance → 各 DBCC コマンドの実行
- Get-DbaDatabase → パイプラインで DBCC コマンドに渡す
- 診断目的では Get-DbaWaitStatistic、Invoke-DbaDiagnosticQuery と組み合わせて使用

**権限による表示制御**：DBCC コマンドの実行には sysadmin 固定サーバーロールのメンバーシップが必要。一部のコマンド（INPUTBUFFER 等）は他のユーザーのセッション情報を取得するため VIEW SERVER STATE 権限も必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 71 | Invoke-DbaDbDbccCheckConstraint | 主機能 | DBCC CHECKCONSTRAINTS を実行し制約違反を検出 |
| 72 | Invoke-DbaDbDbccCleanTable | 補助機能 | DBCC CLEANTABLE で削除列の領域を回収 |
| 73 | Invoke-DbaDbDbccUpdateUsage | 補助機能 | DBCC UPDATEUSAGE でメタデータ不整合を修正 |
| 74 | Invoke-DbaDbccDropCleanBuffer | 補助機能 | DBCC DROPCLEANBUFFERS でバッファキャッシュをクリア |
| 75 | Invoke-DbaDbccFreeCache | 補助機能 | DBCC FREEPROCCACHE/FREESESSIONCACHE/FREESYSTEMCACHE を実行 |
| 66 | Get-DbaDbccHelp | 補助機能 | DBCC HELP でコマンド構文を取得 |
| 67 | Get-DbaDbccMemoryStatus | 補助機能 | DBCC MEMORYSTATUS でメモリ使用状況を取得 |
| 68 | Get-DbaDbccProcCache | 補助機能 | DBCC PROCCACHE でプランキャッシュ統計を取得 |
| 69 | Get-DbaDbccSessionBuffer | 補助機能 | DBCC INPUTBUFFER/OUTPUTBUFFER でセッションバッファを取得 |
| 70 | Get-DbaDbccStatistic | 補助機能 | DBCC SHOW_STATISTICS で統計情報を取得 |

## 画面種別

CLI（コマンドラインインターフェース）/ 一覧・詳細出力

## URL/ルーティング

PowerShell コマンドレットとして呼び出し。URL は存在しない。

```powershell
# 各コマンドの呼び出し例
Invoke-DbaDbDbccCheckConstraint -SqlInstance <インスタンス名>
Get-DbaDbccMemoryStatus -SqlInstance <インスタンス名>
```

## 入出力項目

### 共通入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証情報（Windows認証以外の場合） |
| EnableException | switch | No | 例外処理を有効化 |

### Invoke-DbaDbDbccCheckConstraint 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| Database | string[] | No | 対象データベース |
| Object | string | No | 対象テーブルまたは制約名/ID |
| AllConstraints | switch | No | 有効・無効両方の制約をチェック |
| AllErrorMessages | switch | No | 全違反行を出力（デフォルトは200件まで） |
| NoInformationalMessages | switch | No | 情報メッセージを抑制 |

### Invoke-DbaDbDbccCleanTable 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| Database | string[] | No | 対象データベース |
| Object | string[] | Yes | 対象テーブルまたはオブジェクトID |
| BatchSize | int | No | バッチ処理サイズ |
| NoInformationalMessages | switch | No | 情報メッセージを抑制 |

### Invoke-DbaDbDbccUpdateUsage 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| Database | string[] | No | 対象データベース |
| Table | string | No | 対象テーブル |
| Index | string | No | 対象インデックス |
| NoInformationalMessages | switch | No | 情報メッセージを抑制 |
| CountRows | switch | No | 行カウントも再計算 |

### Get-DbaDbDbccOpenTran 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| Database | string[] | No | 対象データベース |

### Invoke-DbaDbccFreeCache 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| Operation | string | No | FreeProcCache/FreeSessionCache/FreeSystemCache |
| InputValue | string | No | plan_handle、sql_handle、リソースプール名 |
| NoInformationalMessages | switch | No | 情報メッセージを抑制 |
| MarkInUseForRemoval | switch | No | 使用中エントリを削除対象としてマーク |

### Get-DbaDbccStatistic 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| Database | string[] | No | 対象データベース |
| Object | string | No | 対象テーブルまたはビュー |
| Target | string | No | 統計名、インデックス名、列名 |
| Option | string | No | StatHeader/DensityVector/Histogram/StatsStream |
| NoInformationalMessages | switch | No | 情報メッセージを抑制 |

## 表示項目

### Invoke-DbaDbDbccCheckConstraint 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| Cmd | string | 実行されたDBCCコマンド |
| Output | string | DBCC出力メッセージ |
| Table | string | 違反があったテーブル名（違反時のみ） |
| Constraint | string | 違反した制約名（違反時のみ） |
| Where | string | 違反行を特定する条件（違反時のみ） |

### Invoke-DbaDbDbccCleanTable 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| Object | string | 処理対象オブジェクト |
| Cmd | string | 実行されたDBCCコマンド |
| Output | string | DBCC出力メッセージ |

### Get-DbaDbDbccOpenTran 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| DatabaseId | int | データベースID |
| Cmd | string | 実行されたDBCCコマンド |
| Output | string | 結果サマリー |
| Field | string | トランザクション属性名 |
| Data | string | トランザクション属性値 |

### Get-DbaDbccMemoryStatus 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| RecordSet | int | レコードセット番号 |
| RowId | int | 行ID |
| RecordSetId | int | レコードセット内行ID |
| Type | string | メモリカテゴリ |
| Name | string | メトリック名 |
| Value | object | メトリック値 |
| ValueType | string | 値の分類 |

### Get-DbaDbccStatistic 出力（StatHeader オプション時）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| Object | string | テーブル・ビュー名 |
| Target | string | 統計オブジェクト名 |
| Cmd | string | 実行されたDBCCコマンド |
| Name | string | 統計名 |
| Updated | DateTime | 最終更新日時 |
| Rows | long | 行数 |
| RowsSampled | long | サンプル行数 |
| Steps | int | ヒストグラムステップ数 |
| Density | float | 密度値 |
| AverageKeyLength | float | 平均キー長 |
| StringIndex | string | 文字列インデックスフラグ |
| FilterExpression | string | フィルター式 |
| UnfilteredRows | long | フィルター前行数 |
| PersistedSamplePercent | float | サンプル率 |

## イベント仕様

### 1-Invoke-DbaDbDbccCheckConstraint 実行

1. SqlInstance パラメータで指定されたインスタンスに Connect-DbaInstance で接続
2. Database パラメータで指定されたデータベースをフィルタリング
3. 各データベースに対して DBCC CHECKCONSTRAINTS コマンドを構築
4. Object パラメータ指定時は特定テーブル/制約のみチェック
5. WITH オプション（ALL_CONSTRAINTS, ALL_ERRORMSGS, NO_INFOMSGS）を付与
6. Invoke-DbaQuery でコマンド実行
7. 結果が文字列のみの場合は違反なし、DataRow の場合は違反情報を出力

### 2-Invoke-DbaDbDbccCleanTable 実行

1. Object パラメータが必須（未指定時はエラー終了）
2. SqlInstance に接続し、対象データベースを取得
3. 各オブジェクトに対して DBCC CLEANTABLE コマンドを構築
4. BatchSize 指定時はバッチサイズを追加
5. ShouldProcess で確認後、コマンド実行
6. 結果を PSCustomObject として出力

### 3-Invoke-DbaDbDbccUpdateUsage 実行

1. SqlInstance に接続
2. Database パラメータでフィルタリング
3. Table/Index パラメータに応じてコマンドを構築
4. CountRows オプション指定時は WITH COUNT_ROWS を追加
5. コマンド実行後、結果を出力

### 4-Get-DbaDbccMemoryStatus 実行

1. SqlInstance に接続
2. DBCC MEMORYSTATUS を実行し DataTable として取得
3. 各レコードセットをパース
4. Type、Name、Value として構造化
5. PSCustomObject として出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbDbccCheckConstraint | システムテーブル | SELECT | 制約メタデータとデータ行を読み取り |
| Invoke-DbaDbDbccCleanTable | ユーザーテーブル | UPDATE | 削除列の領域を回収しページを圧縮 |
| Invoke-DbaDbDbccUpdateUsage | sys.allocation_units 等 | UPDATE | ページ・行カウントを更新 |
| Invoke-DbaDbccDropCleanBuffer | メモリ構造 | - | バッファプールからクリーンページを削除 |
| Invoke-DbaDbccFreeCache | メモリ構造 | - | 各種キャッシュをクリア |
| Get-DbaDbDbccOpenTran | トランザクションログ | SELECT | アクティブトランザクション情報を読み取り |
| Get-DbaDbccStatistic | sys.stats 等 | SELECT | 統計情報を読み取り |

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

#### sys.allocation_units（Invoke-DbaDbDbccUpdateUsage 時）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | used_pages | 実際のページ数に修正 | カタログビュー修正 |
| UPDATE | data_pages | 実際のページ数に修正 | カタログビュー修正 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | 情報 | "DBCC execution completed. If DBCC printed error messages, contact your system administrator." | DBCC コマンド正常完了 |
| - | 情報 | "No active open transactions." | オープントランザクションなし |
| - | 警告 | "The database {db} is not accessible. Skipping." | データベースアクセス不可 |
| - | エラー | "Failure" | 接続エラー |
| - | エラー | "You must specify a table or indexed view to execute against using -Object" | Object パラメータ未指定（CleanTable時） |
| - | エラー | "You must specify a value for Statement" | Statement パラメータ未指定（GetHelp時） |

## 例外処理

| 例外条件 | ハンドリング | ユーザーへのフィードバック |
|---------|-------------|-------------------------|
| 接続エラー | Stop-Function -Continue | "Failure" メッセージと ConnectionError カテゴリ |
| データベースアクセス不可 | Stop-Function -Continue | "The database {db} is not accessible. Skipping." |
| 必須パラメータ未指定 | Stop-Function + return | パラメータ指定を促すメッセージ |
| DBCCコマンド実行エラー | Stop-Function -Continue | "Error capturing data on {db}" |
| 権限不足 | SQL Server からのエラー | DBCC コマンドのエラーメッセージがそのまま出力 |

## 備考

- DBCC DROPCLEANBUFFERS、DBCC FREEPROCCACHE 等は本番環境での実行に注意が必要（パフォーマンス影響あり）
- 一部の DBCC コマンドは SupportsShouldProcess を実装しており、-WhatIf、-Confirm パラメータが使用可能
- SQL Server 2000 はバージョン制限があり、一部機能が制限される
- 非ドキュメント DBCC コマンドのヘルプ取得には -IncludeUndocumented パラメータが必要

---

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

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

### 推奨読解順序

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

各 DBCC コマンドは PSCustomObject を出力する。出力プロパティはコマンドごとに異なるが、ComputerName、InstanceName、SqlInstance は共通。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbDbccCheckConstraint.ps1 | `public/Invoke-DbaDbDbccCheckConstraint.ps1` | 行 210-240: 出力 PSCustomObject の構造を確認 |

**読解のコツ**: 各関数の末尾にある [PSCustomObject]@{} ブロックで出力形式を確認する。

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

各コマンドは独立した PowerShell 関数として定義されている。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbDbccCheckConstraint.ps1 | `public/Invoke-DbaDbDbccCheckConstraint.ps1` | 行 1-128: 関数定義、パラメータ、ヘルプ |

**主要処理フロー**:
1. **行 140-163**: begin ブロックで DBCC コマンド文字列を StringBuilder で構築
2. **行 165-172**: process ブロックで各インスタンスに接続
3. **行 187-205**: クエリ構築と実行
4. **行 207-241**: 結果の出力処理

#### Step 3: DBCC コマンド構築ロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbDbccCheckConstraint.ps1 | `public/Invoke-DbaDbDbccCheckConstraint.ps1` | 行 140-163: StringBuilder による DBCC 文構築 |
| 3-2 | Invoke-DbaDbDbccFreeCache.ps1 | `public/Invoke-DbaDbccFreeCache.ps1` | 行 131-179: Operation に応じた DBCC 文の分岐構築 |

**主要処理フロー**:
- **行 144-162**: WITH オプションの条件付き追加（AllConstraints, AllErrorMessages, NoInformationalMessages）
- **行 189-197**: Object パラメータの数値/文字列判定とプレースホルダー置換

#### Step 4: 結果パース処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDbccMemoryStatus.ps1 | `public/Get-DbaDbccMemoryStatus.ps1` | 行 86-114: DataTable の多重ループパース |
| 4-2 | Get-DbaDbccStatistic.ps1 | `public/Get-DbaDbccStatistic.ps1` | 行 224-297: Option に応じた出力プロパティの切り替え |

**主要処理フロー**:
- **行 93-96 (MemoryStatus)**: DataSet 内の各 DataTable をループ
- **行 97-113**: 列名を Type、行データを Name/Value として構造化

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

```
Invoke-DbaDbDbccCheckConstraint
    |
    +-- Connect-DbaInstance (接続確立)
    |
    +-- Test-Bound (パラメータ検証)
    |
    +-- StringBuilder.Append (DBCC コマンド構築)
    |
    +-- Invoke-DbaQuery (コマンド実行)
    |       |
    |       +-- $server.Query() (SMO経由でクエリ実行)
    |
    +-- [PSCustomObject] (結果出力)

Get-DbaDbccMemoryStatus
    |
    +-- Connect-DbaInstance
    |
    +-- $server.Query('DBCC MEMORYSTATUS', 'master', $true)
    |       |
    |       +-- 複数DataTableを返却
    |
    +-- foreach ($dataset in $datatable) (DataTable ループ)
    |       |
    |       +-- foreach ($row in $dataset.Rows) (行ループ)
    |
    +-- [PSCustomObject] (構造化出力)
```

### データフロー図

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

SqlInstance    ------>  Connect-DbaInstance
                              |
Database       ------>  フィルタリング
                              |
Object/Target  ------>  DBCC コマンド構築
                              |
                        Invoke-DbaQuery
                              |
                        結果パース (DataRow/String判定)
                              |
                        PSCustomObject 生成  ------->  パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbDbccCheckConstraint.ps1 | `public/Invoke-DbaDbDbccCheckConstraint.ps1` | ソース | 制約整合性チェック |
| Invoke-DbaDbDbccCleanTable.ps1 | `public/Invoke-DbaDbDbccCleanTable.ps1` | ソース | テーブル領域回収 |
| Invoke-DbaDbDbccUpdateUsage.ps1 | `public/Invoke-DbaDbDbccUpdateUsage.ps1` | ソース | 使用量メタデータ更新 |
| Get-DbaDbDbccOpenTran.ps1 | `public/Get-DbaDbDbccOpenTran.ps1` | ソース | オープントランザクション取得 |
| Invoke-DbaDbccDropCleanBuffer.ps1 | `public/Invoke-DbaDbccDropCleanBuffer.ps1` | ソース | バッファキャッシュクリア |
| Invoke-DbaDbccFreeCache.ps1 | `public/Invoke-DbaDbccFreeCache.ps1` | ソース | 各種キャッシュクリア |
| Get-DbaDbccHelp.ps1 | `public/Get-DbaDbccHelp.ps1` | ソース | DBCC ヘルプ取得 |
| Get-DbaDbccMemoryStatus.ps1 | `public/Get-DbaDbccMemoryStatus.ps1` | ソース | メモリ状況取得 |
| Get-DbaDbccProcCache.ps1 | `public/Get-DbaDbccProcCache.ps1` | ソース | プロシージャキャッシュ統計 |
| Get-DbaDbccSessionBuffer.ps1 | `public/Get-DbaDbccSessionBuffer.ps1` | ソース | セッションバッファ取得 |
| Get-DbaDbccStatistic.ps1 | `public/Get-DbaDbccStatistic.ps1` | ソース | 統計情報取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行 |
