# 機能設計書 533-Get-DbaSchemaChangeHistory

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるGet-DbaSchemaChangeHistory機能の設計仕様を定義するものである。この機能はSQL Serverのデフォルトシステムトレースからスキーマ変更履歴（DDL変更）を取得する。

### 本機能の処理概要

**業務上の目的・背景**：データベースオブジェクトに対するCREATE、DROP、ALTER操作の追跡は、コンプライアンス報告、トラブルシューティング、変更管理において必須の機能である。本機能は、デフォルトシステムトレースを照会することで、誰が、いつ、どのオブジェクトを変更したかを特定できる完全な監査証跡を提供する。カスタム監査を有効化したり、手動でトレースファイルを解析する必要がなくなる。

**機能の利用シーン**：
- 障害発生後の原因調査（いつスキーマが変更されたか）
- コンプライアンス監査（変更者・変更内容の追跡）
- 開発環境での変更履歴確認
- 本番環境への意図しない変更検出
- セキュリティインシデント調査

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続（最小バージョン SQL Server 2005）
2. sys.tracesからデフォルトトレースファイルパスを取得
3. 対象データベースの特定とフィルタリング
4. fn_trace_gettableテーブル値関数を使用してトレースデータを読み取り
5. EventClass（46: Create, 47: Drop, 164: Alter）に基づく操作種別分類
6. 指定フィルタ（日時、オブジェクト名）の適用
7. 結果の出力

**関連システム・外部連携**：
- SQL Server Default Trace - システムトレースファイル
- sys.traces - トレース構成情報
- sys.trace_subclass_values - オブジェクトタイプ名解決
- fn_trace_gettable - トレースファイル読み取り関数

**権限による制御**：
- ALTER TRACE権限またはsysadmin固定サーバーロールのメンバーシップが必要
- 対象データベースへのアクセス権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 39 | スキーマ管理 | 補助機能 | スキーマ変更履歴の取得 |

## 機能種別

参照処理（SELECT）/ 監査・履歴取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス。パイプライン入力可能 | 有効なSQL Server接続文字列 |
| SqlCredential | PSCredential | No | SQL Server接続用の代替認証情報 | 有効なPSCredentialオブジェクト |
| Database | object[] | No | 対象データベース。ワイルドカード対応 | - |
| ExcludeDatabase | object[] | No | 除外データベース | - |
| Since | DbaDateTime | No | 指定日時以降の変更のみ取得 | 有効な日時形式 |
| Object | string[] | No | 対象オブジェクト名でフィルタ | - |
| EnableException | switch | No | 例外を呼び出し元にスローする | - |

### 入力データソース

- パラメータ入力（コマンドライン引数）
- SQL Server Default Trace（システムトレースファイル）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾SQL Serverインスタンス名 |
| DatabaseName | string | スキーマ変更が発生したデータベース名 |
| DateModified | DateTime | DDL操作が実行された日時 |
| LoginName | string | 操作を実行したログイン名 |
| UserName | string | Windows認証時のドメイン\ユーザー名 |
| ApplicationName | string | 操作を実行したアプリケーション名 |
| DDLOperation | string | 操作種別（Create/Drop/Alter） |
| Object | string | 変更されたオブジェクト名 |
| ObjectType | string | オブジェクト種別（Table, StoredProcedure等） |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. SQL Server接続（processブロック）
   ├─ Connect-DbaInstance（最小バージョン9）
   └─ エラー時は次のインスタンスへ継続

2. デフォルトトレースパス取得
   ├─ sys.tracesクエリ実行
   └─ トレースファイルなし時は警告出力

3. データベースループ処理
   ├─ Database/ExcludeDatabaseフィルタ適用
   ├─ アクセス不可DBはスキップ
   └─ 各データベースでクエリ実行
       ├─ fn_trace_gettable関数呼び出し
       ├─ sys.trace_subclass_valuesとJOIN
       ├─ Since条件適用
       ├─ Object条件適用
       └─ 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[foreach SqlInstance]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[次のインスタンスへ]
    D -->|Yes| F[sys.traces クエリ]
    F --> G{トレースファイル存在?}
    G -->|No| H[警告出力]
    H --> E
    G -->|Yes| I[データベース一覧取得]
    I --> J[Database/ExcludeDBフィルタ]
    J --> K[foreach db in Databases]
    K --> L{IsAccessible?}
    L -->|No| M[スキップ]
    L -->|Yes| N[DDL履歴クエリ生成]
    N --> O{Since指定?}
    O -->|Yes| P[日時条件追加]
    O -->|No| Q{Object指定?}
    P --> Q
    Q -->|Yes| R[オブジェクト条件追加]
    Q -->|No| S[クエリ実行]
    R --> S
    S --> T[Select-DefaultView]
    T --> U{次のDB?}
    U -->|Yes| K
    U -->|No| V{次のインスタンス?}
    M --> U
    V -->|Yes| B
    V -->|No| W[終了]
    E --> V
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SQL 2005以上必須 | デフォルトシステムトレースはSQL 2005から存在 | 常時 |
| BR-002 | EventClass分類 | 46=Create, 47=Drop, 164=Alter | DDL操作分類時 |
| BR-003 | ObjectType除外 | ObjectType 21587は除外 | クエリ実行時 |
| BR-004 | EventSubClass条件 | EventSubClass = 0のみ対象 | クエリ実行時 |
| BR-005 | トレース有効必須 | デフォルトトレースが有効でない場合は結果なし | 常時 |

### 計算ロジック

DDLOperation変換ロジック:
```
EventClass 46  -> 'Create'
EventClass 47  -> 'Drop'
EventClass 164 -> 'Alter'
```

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

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

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

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

#### sys.traces

```sql
SELECT path FROM sys.traces WHERE is_default = 1
```

#### fn_trace_gettable + sys.trace_subclass_values

```sql
SELECT  SERVERPROPERTY('MachineName') ComputerName
      , ISNULL(SERVERPROPERTY('InstanceName'), 'MSSQLSERVER') InstanceName
      , SERVERPROPERTY('ServerName') SqlInstance
      , tt.DatabaseName DatabaseName
      , tt.StartTime DateModified
      , tt.SessionLoginName LoginName
      , tt.NTUserName UserName
      , tt.ApplicationName ApplicationName
      , CASE tt.EventClass
             WHEN '46' THEN 'Create'
             WHEN '47' THEN 'Drop'
             WHEN '164' THEN 'Alter'
        END DDLOperation
      , tt.ObjectName Object
      , ISNULL(tsv.subclass_name, 'Unknown') ObjectType
FROM    ::fn_trace_gettable('トレースファイルパス',DEFAULT) tt
        LEFT JOIN sys.trace_subclass_values tsv ON
            tsv.trace_event_id = tt.EventClass
            AND tsv.subclass_value = tt.ObjectType
            AND tsv.trace_column_id = 28
WHERE   tt.ObjectType NOT IN ( 21587 )
        AND tt.DatabaseID = DB_ID()
        AND tt.EventSubClass = 0
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server接続失敗 | 接続情報・ネットワークを確認 |
| - | トレースなし | デフォルトトレースが無効 | sp_configure 'default trace enabled' を確認 |
| - | データなし | 条件に合致する変更履歴なし | フィルタ条件を見直す |

### リトライ仕様

Stop-Function -Continueにより、複数インスタンス処理時にエラーが発生しても次のインスタンス処理を継続する。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

- トレースファイルのサイズによっては読み込みに時間がかかる場合がある
- 多数のデータベースを対象とする場合は順次処理
- Since条件を指定することでパフォーマンス向上可能

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

- ALTER TRACE権限が必要
- ログイン名、ユーザー名、アプリケーション名などのセキュリティ関連情報を取得
- 監査目的での使用に適している

## 備考

- デフォルトトレースはSQL Server起動時に自動開始
- トレースファイルは自動ローテーションされ、古いデータは失われる可能性
- カスタム監査が必要な場合はSQL Server AuditやExtended Eventsを検討

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | 出力プロパティ定義（134-148行目のSQLクエリSELECT句） |

**読解のコツ**: SQLクエリ内のSELECT句で定義されるカラムが出力プロパティとなる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | param()ブロック（94-104行目）でパラメータ定義確認 |

**主要処理フロー**:
1. **106行目**: processブロック開始
2. **107-112行目**: SQL Server接続（MinimumVersion 9）
3. **114-121行目**: デフォルトトレースパス取得クエリ
4. **123-128行目**: データベースフィルタリング
5. **129-169行目**: 各データベースでのDDL履歴クエリ実行

#### Step 3: クエリ構築ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | 134-165行目のSQL動的構築 |

**主要処理フロー**:
- **134-156行目**: 基本クエリ（fn_trace_gettable + JOIN）
- **158-160行目**: Since条件の動的追加
- **161-163行目**: Object条件の動的追加
- **165行目**: ORDER BY追加

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

```
Get-DbaSchemaChangeHistory
    │
    ├─ Connect-DbaInstance（SQL Server接続）
    │      └─ MinimumVersion 9（SQL 2005）
    │
    ├─ server.Query()
    │      └─ sys.traces クエリ（トレースパス取得）
    │
    ├─ server.Databases
    │      └─ Where-Object（Database/ExcludeDatabase フィルタ）
    │
    └─ db.Query()
           └─ fn_trace_gettable + sys.trace_subclass_values
                  └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance ───────▶ SMO Server
                              │
                              ▼
                       sys.traces クエリ ─────────▶ トレースファイルパス
                              │
Database ───────────────────┤
ExcludeDatabase ────────────┤
                              ▼
                       server.Databases ──────────▶ Filtered DB List
                              │
Since ──────────────────────┤
Object ─────────────────────┤
                              ▼
                       fn_trace_gettable
                       + sys.trace_subclass_values
                              │
                              ▼
                       Select-DefaultView ────────▶ PSCustomObject[]
                                                    (ComputerName,
                                                     InstanceName,
                                                     SqlInstance,
                                                     DatabaseName,
                                                     DateModified,
                                                     LoginName,
                                                     UserName,
                                                     ApplicationName,
                                                     DDLOperation,
                                                     Object,
                                                     ObjectType)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaSchemaChangeHistory.ps1 | `public/Get-DbaSchemaChangeHistory.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続共通関数 |
| Select-DefaultView.ps1 | `private/Select-DefaultView.ps1` | ソース | デフォルト表示プロパティ設定 |
