# 機能設計書 135-Get-DbaOpenTransaction

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaOpenTransaction`コマンドレットに関する機能設計書です。このコマンドレットは、SQL Serverインスタンス全体のオープントランザクションに関する詳細情報を取得する機能を提供します。

### 本機能の処理概要

**業務上の目的・背景**：オープン（未コミット）トランザクションは、ブロッキング、トランザクションログの肥大化、パフォーマンス低下の主要な原因となります。本機能は、SQL Serverの動的管理ビュー（DMV）を使用してオープントランザクションを特定し、セッション情報、データベースコンテキスト、トランザクション継続時間、ログ使用量、最後に実行されたクエリと実行プランを取得します。これにより、DBAは問題のあるトランザクションを迅速に特定し、対処できます。

**機能の利用シーン**：
- ブロッキング問題のトラブルシューティング時
- 長時間実行されているトランザクションの調査時
- トランザクションログの急激な増加の原因調査時
- システムパフォーマンス監視時

**主要な処理内容**：
1. SQL Serverインスタンスに接続（最小バージョン：SQL Server 2005）
2. DMV（dm_tran_database_transactions, dm_tran_session_transactions等）をクエリ
3. セッション情報、トランザクション情報、最後のクエリと実行プランを結合
4. 結果をPSCustomObjectとして出力

**関連システム・外部連携**：
- SQL Server DMV（sys.dm_tran_database_transactions, sys.dm_tran_session_transactions等）
- Connect-DbaInstance（SQL Server接続）

**権限による制御**：VIEW SERVER STATE権限が必要です。実行プランの取得にはこの権限が必須です。

## 関連画面

本機能はコマンドラインツールであり、画面機能マッピングに該当する関連画面はありません。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | PowerShellコマンドラインで実行 |

## 機能種別

データ取得 / 診断・監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可、Mandatory |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- SQL Server DMV:
  - sys.dm_tran_database_transactions
  - sys.dm_tran_session_transactions
  - sys.dm_exec_sessions
  - sys.dm_exec_connections
  - sys.dm_exec_requests
  - sys.dm_exec_sql_text
  - sys.dm_exec_query_plan

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（デフォルトインスタンスは'MSSQLSERVER'） |
| SqlInstance | string | サーバーに登録されている完全なインスタンス名 |
| Spid | int | トランザクションを保持しているセッションID |
| Login | string | セッションに関連付けられたログイン名 |
| Database | string | トランザクションがオープンしているデータベース名 |
| BeginTime | datetime | トランザクション開始日時 |
| LogBytesUsed | bigint | 現在このトランザクションが使用しているトランザクションログのバイト数 |
| LogBytesReserved | bigint | このトランザクションのために予約されているトランザクションログのバイト数 |
| LastQuery | string | セッションで最後に実行されたSQLコマンドのテキスト |
| LastPlan | xml | 最後に実行されたクエリの実行プランXML（利用不可の場合はNULL） |

### 出力先

PowerShellパイプライン（System.Management.Automation.PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. beginブロック: SQLクエリ定義
   └─ DMVを結合するT-SQLクエリを構築

2. processブロック: 各インスタンスに対して処理
   ├─ Connect-DbaInstanceで接続（MinimumVersion 9=SQL 2005）
   └─ Server.Queryでクエリ実行・結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ定義]
    B --> C{各SqlInstanceに対して}
    C --> D[Connect-DbaInstance -MinimumVersion 9]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G[$server.Query実行]
    G --> H[結果出力]
    H --> C
    C -->|完了| I[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン制限 | SQL Server 2005以降が必要 | 常時 |
| BR-002 | 時系列ソート | BeginTime昇順でソート（古いトランザクションが先） | 常時 |
| BR-003 | サーバー名取得 | SERVERPROPERTY関数でサーバー情報取得 | 常時 |

### 計算ロジック

SQLクエリの結合ロジック：
1. dm_tran_database_transactions と dm_tran_session_transactions を transaction_id で結合
2. dm_exec_sessions を session_id で結合
3. dm_exec_connections を session_id で結合
4. dm_exec_requests を session_id で LEFT OUTER JOIN
5. dm_exec_sql_text を most_recent_sql_handle で CROSS APPLY
6. dm_exec_query_plan を plan_handle で OUTER APPLY

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トランザクション情報取得 | sys.dm_tran_database_transactions | SELECT | データベーストランザクション情報取得 |
| セッション情報取得 | sys.dm_tran_session_transactions | SELECT | セッションとトランザクションの関連取得 |
| セッション詳細取得 | sys.dm_exec_sessions | SELECT | セッション詳細情報取得 |
| 接続情報取得 | sys.dm_exec_connections | SELECT | 接続情報取得 |
| リクエスト情報取得 | sys.dm_exec_requests | SELECT | 現在実行中のリクエスト取得 |
| クエリテキスト取得 | sys.dm_exec_sql_text | SELECT | SQLテキスト取得 |
| 実行プラン取得 | sys.dm_exec_query_plan | SELECT | 実行プラン取得 |

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

#### sys.dm_tran_database_transactions (s_tdt)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | database_id | DB_NAME()で名前変換 | - |
| SELECT | database_transaction_begin_time | BeginTimeとして出力 | - |
| SELECT | database_transaction_log_bytes_used | LogBytesUsedとして出力 | - |
| SELECT | database_transaction_log_bytes_reserved | LogBytesReservedとして出力 | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Serverへの接続失敗 | Stop-Function (ConnectionError) で処理継続 |
| - | バージョンエラー | SQL Server 2000への接続試行 | Connect-DbaInstance -MinimumVersion 9 で拒否 |

### リトライ仕様

リトライ処理は実装されていません。

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

読み取り専用クエリのため、トランザクション管理は不要です。

## パフォーマンス要件

- DMVへのクエリはリアルタイムでシステム状態を反映
- 大量のオープントランザクションがある場合でも数秒以内で完了

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

- VIEW SERVER STATE権限が必要
- SqlCredentialで認証情報を安全に取り扱い
- LastQueryにはセキュリティ上機密なSQLが含まれる可能性がある

## 備考

- このコマンドはPaul Randal氏のオープントランザクション監視スクリプトに基づいている
- 参考: https://www.sqlskills.com/blogs/paul/script-open-transactions-with-text-and-plans/
- オープントランザクションがない場合は何も出力されない

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | 38-54行目: .OUTPUTS セクションで出力型の説明 |

**読解のコツ**: SQLクエリ結果がそのままPSCustomObjectとして出力される点に注目。

#### Step 2: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | 78-113行目: T-SQLクエリ定義 |

**主要処理フロー**:
1. **79-89行目**: SELECT句 - 出力カラムの定義
2. **90-111行目**: FROM/JOIN句 - DMV結合ロジック
3. **112-113行目**: ORDER BY - BeginTime昇順ソート

#### Step 3: メイン処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | 115-125行目: processブロック |

**主要処理フロー**:
- **117-121行目**: Connect-DbaInstance -MinimumVersion 9 で接続
- **123行目**: $server.Query($sql) でクエリ実行

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

```
Get-DbaOpenTransaction
    │
    ├─ begin ブロック
    │      └─ T-SQLクエリ定義 ($sql)
    │
    └─ process ブロック
           │
           └─ foreach ($instance in $SqlInstance)
                  │
                  ├─ Connect-DbaInstance -MinimumVersion 9
                  │      └─ [失敗時] Stop-Function
                  │
                  └─ $server.Query($sql)
                         │
                         └─ 結果をパイプラインに出力
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance
                           │
                           ▼
                    $server.Query($sql)
                           │
                           ▼
                    DMV結合クエリ実行
                           │
  dm_tran_database_transactions ──┐
  dm_tran_session_transactions ───┤
  dm_exec_sessions ───────────────┼──▶ 結合結果
  dm_exec_connections ────────────┤
  dm_exec_requests ───────────────┤
  dm_exec_sql_text ───────────────┤
  dm_exec_query_plan ─────────────┘
                           │
                           ▼
                    PSCustomObject ───────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | ソース | メイン処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/flowcontrol/Stop-Function.ps1` | ソース | エラー処理 |
