# 画面設計書 237-トランザクションログ読み取り

## 概要

本ドキュメントは、dbatools PowerShell モジュールの `Read-DbaTransactionLog` コマンドに関する設計書です。このコマンドは、SQL Server の fn_dblog 関数を使用してデータベースの生トランザクションログレコードを取得し、フォレンジック分析やトラブルシューティングに必要なデータを提供します。

### 本画面の処理概要

**業務上の目的・背景**：データベースで何が起こったかを詳細に調査する必要がある場合、トランザクションログは最も信頼性の高い情報源です。本コマンドは SQL Server の内部関数 fn_dblog を使用して、削除されたレコードの追跡、特定の変更が発生した時刻の特定、トランザクションパターンの分析などのフォレンジック調査を可能にします。

**画面へのアクセス方法**：PowerShell コンソールまたはスクリプトから `Read-DbaTransactionLog` コマンドを実行します。

**主要な操作・処理内容**：
1. SQL Server インスタンスに接続
2. 対象データベースの存在と状態を確認
3. ログサイズの安全性チェック（0.5GB 制限）
4. fn_dblog(NULL,NULL) を実行してトランザクションログを取得
5. 結果をパイプラインに出力

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

**権限による表示制御**：対象データベースへのアクセス権限が必要です。fn_dblog の実行には適切な権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 197 | Read-DbaTransactionLog | 主機能 | トランザクションログの読み取り |
| 90 | Connect-DbaInstance | 補助機能 | SQL Server インスタンスへの接続 |

## 画面種別

CLI コマンド（データ読み取り・フォレンジック分析）

## URL/ルーティング

PowerShell コマンド: `Read-DbaTransactionLog`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | Yes | SQL Server インスタンス |
| SqlCredential | PSCredential | No | SQL Server 認証情報 |
| Database | object | Yes | 対象データベース名 |
| IgnoreLimit | switch | No | 0.5GB 制限を無視 |
| RowLimit | int | No | 取得行数制限 |
| EnableException | switch | No | 例外を有効化 |

### 出力項目

fn_dblog から返される全カラムが出力されます。主なプロパティ：

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| RecoveryUnitId | int | リカバリユニット識別子 |
| LSN | string | ログシーケンス番号 |
| LOP | string | ログ操作タイプ |
| Transaction ID | string | トランザクション識別子 |
| BeginTime | datetime | 操作開始時刻 |
| AllocUnitName | string | 影響を受けた割り当てユニット名 |
| RowIdentifier | string | 影響を受けた行の識別子 |
| XactId | string | 拡張トランザクション ID |
| Context | string | 操作コンテキストフラグ |
| AllocUnitId | bigint | 割り当てユニット ID |
| ObjectId | int | テーブル/インデックスのオブジェクト ID |
| IndexId | int | インデックス ID |
| PageId | string | 影響を受けたページ ID |
| その他 | various | fn_dblog の全カラム |

## 表示項目

fn_dblog から返される全カラムが出力されます。カラム構成は SQL Server のバージョンと記録されている操作の種類によって異なります。

## イベント仕様

### 1-コマンド実行

1. SQL Server インスタンスへの接続
2. データベースの存在確認
3. データベースの状態確認（'Normal' 状態のみ）
4. RowLimit 指定時は IgnoreLimit を自動有効化
5. IgnoreLimit 未指定時はログサイズチェック（0.5GB 制限）
6. fn_dblog(NULL,NULL) クエリの実行
7. 結果をパイプラインに出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ログ読み取り | fn_dblog | SELECT | トランザクションログ読み取り |
| サイズチェック | sys.sysfiles | SELECT | ログファイルサイズ確認 |

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

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

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| Verbose | "Limiting results to $RowLimit rows" | RowLimit 指定時 |
| Verbose | "Please be aware that ignoring the recommended limits may impact on the performance" | IgnoreLimit 有効時 |
| Verbose | "Starting Log retrieval" | ログ取得開始時 |
| Error | "$Database does not exist" | データベース不存在 |
| Error | "$Database is not in a normal State" | 状態異常 |
| Error | "$Database has more than 0.5 Gb of live log data" | ログサイズ超過 |
| Error | "Failure" | 接続エラー |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Function で処理停止 |
| データベース不存在 | Stop-Function で処理停止 |
| 状態異常 | Stop-Function で処理停止 |
| ログサイズ超過 | Stop-Function で処理停止（IgnoreLimit で回避可能） |

## 備考

- fn_dblog(NULL,NULL) は全ログレコードを返す
- 0.5GB 制限はパフォーマンス影響を防ぐための安全機構
- IgnoreLimit 使用時は SQL Server インスタンスへのパフォーマンス影響に注意
- RowLimit 指定時は TOP 句を追加（自動的に IgnoreLimit が有効化）
- データベースは 'Normal' 状態である必要がある（AG セカンダリ等では動作しない場合あり）
- 出力カラムは SQL Server バージョンと記録された操作によって異なる
- Select-Object * で全プロパティを確認可能

---

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

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

### 推奨読解順序

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

fn_dblog から返されるデータ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Read-DbaTransactionLog.ps1 | `public/Read-DbaTransactionLog.ps1` | 行140-143: SQL クエリと結果出力 |

**読解のコツ**: fn_dblog は SQL Server 内部関数であり、返されるカラムはバージョンによって異なる。

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

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

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

**主要処理フロー**:
1. **行99-104**: 接続処理
2. **行106-108**: データベース存在確認
3. **行110-114**: データベース状態確認
4. **行116-122**: RowLimit 処理
5. **行125-138**: ログサイズチェック（IgnoreLimit 未指定時）
6. **行140-143**: fn_dblog クエリ実行

#### Step 3: 安全機構を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Read-DbaTransactionLog.ps1 | `public/Read-DbaTransactionLog.ps1` | 行129-137: ログサイズチェック |

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

```
Read-DbaTransactionLog
    │
    ├─ Connect-DbaInstance (行100)
    │      └─ SQL Server SMO 接続
    │
    ├─ $server.databases[$Database] (行106)
    │      └─ データベース存在確認
    │
    ├─ Status チェック (行110-114)
    │      └─ 'Normal' 状態確認
    │
    ├─ ログサイズチェック (行129-137)
    │      └─ sys.sysfiles クエリ
    │
    └─ $server.Query($sql, $Database) (行143)
           └─ fn_dblog 実行
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ───────────▶ Server Object
                               │
Database ──────────────▶ 存在・状態チェック ──────────────▶ 有効なDB
                               │
IgnoreLimit ───────────▶ サイズチェック判定
                               │
RowLimit ──────────────▶ TOP 句追加
                               │
                         fn_dblog(NULL,NULL) 実行
                               │
                         結果出力 ─────────────────────────▶ PSCustomObject[]
```

### 関連ファイル一覧

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