# 画面設計書 238-スキーマ変更履歴

## 概要

本ドキュメントは、dbatools PowerShell モジュールの `Get-DbaSchemaChangeHistory` コマンドに関する設計書です。このコマンドは、SQL Server のデフォルトシステムトレースから DDL 変更履歴（CREATE、DROP、ALTER 操作）を取得し、コンプライアンス報告やトラブルシューティングに必要な監査データを提供します。

### 本画面の処理概要

**業務上の目的・背景**：データベーススキーマの変更履歴を追跡することは、セキュリティ監査、コンプライアンス報告、問題のトラブルシューティングにおいて重要です。本コマンドは、デフォルトシステムトレースを解析して、誰が、いつ、どのオブジェクトに対して、どのような DDL 操作を行ったかを特定します。カスタム監査を設定することなく、SQL Server 2005 以降で利用可能です。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから `Get-DbaSchemaChangeHistory` コマンドを実行します。パイプライン入力として SQL Server インスタンスを受け取ることも可能です。

**主要な操作・処理内容**：
1. SQL Server インスタンスに接続（最小バージョン: SQL Server 2005）
2. デフォルトシステムトレースファイルのパスを取得
3. 対象データベースをフィルタリング
4. fn_trace_gettable でトレースデータを取得
5. EventClass（46=Create、47=Drop、164=Alter）をフィルタリング
6. 結果をパイプラインに出力

**画面遷移**：CLI コマンドのため画面遷移は存在しませんが、出力結果は Export-Csv や Where-Object などにパイプライン接続可能です。

**権限による表示制御**：デフォルトトレースファイルへのアクセス権限と、対象データベースへのアクセス権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 533 | Get-DbaSchemaChangeHistory | 主機能 | スキーマ変更履歴の取得 |
| 90 | Connect-DbaInstance | 補助機能 | SQL Server インスタンスへの接続 |

## 画面種別

CLI コマンド（履歴取得・監査）

## URL/ルーティング

PowerShell コマンド: `Get-DbaSchemaChangeHistory`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | SQL Server インスタンス |
| SqlCredential | PSCredential | No | SQL Server 認証情報 |
| Database | object[] | No | 対象データベース |
| ExcludeDatabase | object[] | No | 除外するデータベース |
| Since | DbaDateTime | No | 指定日時以降の変更のみ取得 |
| Object | string[] | No | 対象オブジェクト名 |
| EnableException | switch | No | 例外を有効化 |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| DatabaseName | string | データベース名 |
| DateModified | datetime | 変更日時 |
| LoginName | string | ログイン名 |
| UserName | string | Windows ユーザー名 |
| ApplicationName | string | 実行元アプリケーション |
| DDLOperation | string | DDL 操作種別（Create/Drop/Alter） |
| Object | string | オブジェクト名 |
| ObjectType | string | オブジェクトタイプ |

## 表示項目

デフォルト表示プロパティ:
- ComputerName
- InstanceName
- SqlInstance
- DatabaseName
- DateModified
- LoginName
- UserName
- ApplicationName
- DDLOperation
- Object
- ObjectType

### DDLOperation の値

| 値 | EventClass | 説明 |
|----|-----------|------|
| Create | 46 | CREATE 操作 |
| Drop | 47 | DROP 操作 |
| Alter | 164 | ALTER 操作 |

## イベント仕様

### 1-コマンド実行

1. SQL Server インスタンスへの接続（最小バージョン: SQL Server 2005）
2. sys.traces からデフォルトトレースファイルパスを取得
3. Database/ExcludeDatabase でデータベースをフィルタリング
4. 各データベースに対して fn_trace_gettable クエリを実行:
   - EventClass 46, 47, 164 をフィルタリング
   - EventSubClass = 0 に限定
   - ObjectType 21587 を除外
   - Since 指定時は日時フィルタ追加
   - Object 指定時はオブジェクト名フィルタ追加
5. 結果をパイプラインに出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| トレースファイル取得 | sys.traces | SELECT | デフォルトトレースパス取得 |
| 変更履歴取得 | fn_trace_gettable | SELECT | トレースデータ取得 |
| オブジェクトタイプ取得 | sys.trace_subclass_values | SELECT | タイプ名変換 |

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

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

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Verbose | "Querying Database $db on $instance" | データベース検索時 |
| Verbose | "$($db.name) is not accessible, skipping" | データベースアクセス不可 |
| Warning | "No default trace file found on $instance." | トレースファイルなし |
| Error | "Failure" | 接続エラー |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Function で警告、次のインスタンスへ続行 |
| トレースファイルなし | Warning を出力、次のインスタンスへ続行 |
| データベースアクセス不可 | Verbose を出力、次のデータベースへ続行 |
| SQL Server 2000 以前 | MinimumVersion 9 により接続拒否 |

## 備考

- SQL Server 2005 以降が必要（デフォルトトレースが存在しないため）
- デフォルトトレースが無効化されている場合は結果が取得できない
- EventSubClass = 0 は完了したイベントのみを取得
- ObjectType 21587 は除外（特定のシステムイベント）
- sys.trace_subclass_values との結合で ObjectType を人間が読める形式に変換
- Since パラメータで日時フィルタリング可能
- Object パラメータで特定オブジェクトの変更のみ取得可能
- トレースファイルの保持期間は SQL Server の設定に依存

---

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

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

### 推奨読解順序

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

出力される PSCustomObject の構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | 行134-148: SQL クエリの SELECT 句 |

**読解のコツ**: fn_trace_gettable の出力カラムとの対応を理解する。

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

処理の起点となるファイル・関数を特定します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | 関数全体の構造と処理フロー |

**主要処理フロー**:
1. **行107-112**: 接続処理（MinimumVersion 9）
2. **行114-115**: デフォルトトレースファイルパス取得
3. **行117-121**: トレースファイル存在確認
4. **行123-127**: データベースフィルタリング
5. **行129-169**: 各データベースに対するクエリ実行

#### Step 3: SQL クエリ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | 行134-156: メイン SQL クエリ |
| 3-2 | Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | 行142-146: EventClass の変換 |

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

```
Get-DbaSchemaChangeHistory
    │
    ├─ Connect-DbaInstance (行109)
    │      └─ SQL Server SMO 接続（MinimumVersion 9）
    │
    ├─ sys.traces クエリ (行114-116)
    │      └─ デフォルトトレースパス取得
    │
    ├─ データベースフィルタリング (行123-127)
    │      ├─ Database パラメータ
    │      └─ ExcludeDatabase パラメータ
    │
    └─ $db.Query($sql) (行169)
           └─ fn_trace_gettable + sys.trace_subclass_values
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ───────────▶ Server Object
                               │
                         sys.traces クエリ ─────────────────▶ TraceFile Path
                               │
Database/ExcludeDatabase ─────▶ フィルタリング ─────────────▶ 対象 DB リスト
                               │
Since/Object ─────────────────▶ WHERE 句構築
                               │
                         fn_trace_gettable クエリ
                               │
                         Select-DefaultView ────────────────▶ PSCustomObject[]
```

### 関連ファイル一覧

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