# 画面設計書 172-疑わしいページ

## 概要

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

### 本画面の処理概要

本コマンドは、SQL Server msdbデータベースの suspect_pages テーブルからデータベース破損情報を取得し、破損検出と分析を支援します。

**業務上の目的・背景**：データベース破損はデータ損失やアプリケーション障害の原因となる深刻な問題です。SQL Serverは読み取り操作中に検出した破損ページ（チェックサムエラー、ページ破損、I/Oエラーなど）を msdb.dbo.suspect_pages テーブルに自動的に記録します。本コマンドを使用することで、DBAは破損ページを事前に検出し、DBCC CHECKDB の実行やバックアップからのリストアなどの対策を講じることができます。

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

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスに接続（SQL Server 2005以上が必要）
2. msdb.dbo.suspect_pages テーブルをクエリしてイベントタイプ、エラーカウント、最終更新日を取得
3. イベントタイプコードを人間が理解しやすい説明に変換
4. 指定されたデータベースでフィルタリング（オプション）
5. 結果をPSCustomObjectとしてパイプラインに出力

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

**権限による表示制御**：msdb.dbo.suspect_pages テーブルへの読み取り権限が必要です。通常、sysadmin、msdb_dbo のメンバー、またはSELECT権限を持つユーザーがアクセスできます。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 148 | Get-DbaSuspectPage | 主機能 | 疑わしいページの取得 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド: `Get-DbaSuspectPage`

## 入出力項目

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| Database | object | No | フィルタリング対象データベース名 |
| SqlCredential | PSCredential | No | 認証用資格情報 |
| EnableException | switch | No | 例外処理モードの有効化 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|---|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | 疑わしいページを含むデータベース名 |
| FileId | int | 破損ページが存在するファイルID |
| PageId | int | 疑わしいページのページID |
| EventType | string | 破損イベントの種類（823 or 824、Bad Checksum、Torn Page、Restored、Repaired (DBCC)、Deallocated (DBCC)） |
| ErrorCount | int | このページが疑わしいと検出された回数 |
| LastUpdateDate | datetime | ページが最後に疑わしいと検出された日時 |

## イベント仕様

### 1-コマンド実行

1. SqlInstanceパラメータを検証
2. 指定されたインスタンスに接続（MinimumVersion 9 = SQL Server 2005以上）
3. msdb.dbo.suspect_pages テーブルに対してSELECTクエリを実行
4. event_type コードを説明文に変換（CASE文）
5. Databaseパラメータが指定された場合、結果をフィルタリング
6. 各行に対してPSCustomObjectを生成しパイプラインに出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行 | msdb.dbo.suspect_pages | SELECT | 疑わしいページ情報の取得 |

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

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

## メッセージ仕様

| メッセージID | 種別 | 条件 | メッセージ内容 |
|-------------|------|------|--------------|
| M001 | Error | 接続失敗 | "Failure" |
| M002 | Error | データ取得失敗 | "Issue collecting data on {server}" |

## 例外処理

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

## 備考

- 疑わしいページが存在しない場合、出力はありません
- イベントタイプの意味:
  - 823 or 824: I/Oエラー（ハードウェア障害の可能性）
  - Bad Checksum: ページチェックサム検証失敗
  - Torn Page: ページ破損検出
  - Restored: バックアップからリストア済み
  - Repaired (DBCC): DBCC CHECKDBで修復済み
  - Deallocated (DBCC): DBCC CHECKDBで割り当て解除済み

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とsuspect_pagesテーブルのスキーマを理解します。

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

**読解のコツ**: 出力プロパティは suspect_pages テーブルのカラムと1対1で対応しています。EventTypeは数値から説明文に変換されています。

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

processブロックの処理フローを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaSuspectPage.ps1 | `public/Get-DbaSuspectPage.ps1` | 75-123行目：processブロック全体 |

**主要処理フロー**:
1. **76-81行目**: インスタンスへの接続（SQL Server 2005以上必須）
2. **83-97行目**: SQLクエリの定義（event_type変換を含む）
3. **99-103行目**: クエリ実行
4. **105-107行目**: Databaseパラメータでのフィルタリング
5. **110-122行目**: 結果のオブジェクト変換と出力

#### Step 3: イベントタイプ変換を理解する

event_typeコードの変換ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaSuspectPage.ps1 | `public/Get-DbaSuspectPage.ps1` | 87-94行目：CASE文によるevent_type変換 |

**主要処理フロー**:
- 1 = "823 or 824" (I/Oエラー)
- 2 = "Bad Checksum"
- 3 = "Torn Page"
- 4 = "Restored"
- 5 = "Repaired (DBCC)"
- 7 = "Deallocated (DBCC)"

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

```
Get-DbaSuspectPage
    |
    +-- Connect-DbaInstance (接続、MinimumVersion=9)
    |
    +-- $server.Query() (SQLクエリ実行)
    |
    +-- Where-Object (Databaseフィルタリング)
    |
    +-- PSCustomObject (結果オブジェクト生成)
```

### データフロー図

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

SqlInstance   ---> Connect-DbaInstance ---> $server
                        |
                        v
                   Query: SELECT from
                   msdb.dbo.suspect_pages
                        |
                        v
                   CASE変換 +         ---> PSCustomObject
                   Where-Object           (整形された結果)
```

### 関連ファイル一覧

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