# 画面設計書 165-オープントランザクション

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるオープントランザクション取得機能（Get-DbaOpenTransaction）の画面設計書です。SQL Serverインスタンス全体でオープン状態（未コミット/未ロールバック）のトランザクションを詳細に取得する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：長時間オープンしたままのトランザクションは、ブロッキングの原因となり、トランザクションログの肥大化を引き起こし、システム全体のパフォーマンスに悪影響を与えます。本機能は、オープントランザクションを迅速に特定し、セッション情報、データベースコンテキスト、トランザクション継続時間、ログ使用量、最終実行クエリと実行プランを包括的に取得します。これにより、DBAsはブロッキング問題の調査、長時間実行トランザクションの監視、トランザクションログ増加の原因調査を効率的に行えます。

**画面へのアクセス方法**：PowerShellコマンドラインから `Get-DbaOpenTransaction` コマンドレットを実行してアクセスします。

**主要な操作・処理内容**：
1. SQL Serverインスタンスに接続（SQL Server 2005以上が必要）
2. sys.dm_tran_database_transactions、sys.dm_tran_session_transactions、sys.dm_exec_sessions、sys.dm_exec_connections、sys.dm_exec_requestsを結合クエリ
3. sys.dm_exec_sql_text、sys.dm_exec_query_planで最終クエリと実行プランを取得
4. オープントランザクション情報をPSCustomObjectとして出力

**画面遷移**：本機能は単独のコマンドレットとして動作します。出力からSPIDを取得してStop-DbaProcessと連携可能です。

**権限による表示制御**：sys.dm_tran_*ビューへのアクセスにはVIEW SERVER STATE権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 135 | Get-DbaOpenTransaction | 主機能 | オープントランザクションの取得 |
| 65 | Get-DbaDbDbccOpenTran | 補助機能 | DBCC OPENTRANの実行 |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続 |

## 画面種別

CLI（コマンドラインインターフェース）- 診断・監視

## URL/ルーティング

PowerShellコマンド: `Get-DbaOpenTransaction`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| EnableException | switch | No | 例外を有効化 |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Spid | int | セッションID（SPID） |
| Login | string | ログイン名 |
| Database | string | トランザクションが存在するデータベース |
| BeginTime | DateTime | トランザクション開始日時 |
| LogBytesUsed | bigint | 使用中のトランザクションログバイト数 |
| LogBytesReserved | bigint | 予約済みトランザクションログバイト数 |
| LastQuery | string | 最終実行SQLテキスト |
| LastPlan | xml | 最終実行クエリの実行プラン（利用可能な場合） |

## 表示項目

出力オブジェクトのすべてのプロパティがPowerShellコンソールに表示されます。LastPlanはXML形式で、別途解析やSSMSでの可視化が可能です。

## イベント仕様

### 1-コマンド実行

1. **クエリ定義**（行78-113）: beginブロックで複雑なDMV結合クエリを定義
2. **SQL Server接続**（行117-121）: Connect-DbaInstance（-MinimumVersion 9でSQL 2005+を要求）
3. **クエリ実行**（行123）: server.Query($sql)でオープントランザクション情報を取得

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| トランザクション取得 | 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 | CROSS APPLY | 最終実行SQLテキスト |
| 実行プラン取得 | sys.dm_exec_query_plan | OUTER APPLY | 実行プランXML |

### クエリ詳細

```sql
SELECT
    SERVERPROPERTY('MachineName') AS ComputerName,
    ISNULL(SERVERPROPERTY('InstanceName'), 'MSSQLSERVER') AS InstanceName,
    SERVERPROPERTY('ServerName') AS SqlInstance,
    [s_tst].[session_id] AS Spid,
    [s_es].[login_name] AS Login,
    DB_NAME (s_tdt.database_id) AS [Database],
    [s_tdt].[database_transaction_begin_time] AS [BeginTime],
    [s_tdt].[database_transaction_log_bytes_used] AS [LogBytesUsed],
    [s_tdt].[database_transaction_log_bytes_reserved] AS [LogBytesReserved],
    [s_est].text AS [LastQuery],
    [s_eqp].[query_plan] AS [LastPlan]
FROM sys.dm_tran_database_transactions [s_tdt]
JOIN sys.dm_tran_session_transactions [s_tst] ON [s_tst].[transaction_id] = [s_tdt].[transaction_id]
JOIN sys.dm_exec_sessions [s_es] ON [s_es].[session_id] = [s_tst].[session_id]
JOIN sys.dm_exec_connections [s_ec] ON [s_ec].[session_id] = [s_tst].[session_id]
LEFT OUTER JOIN sys.dm_exec_requests [s_er] ON [s_er].[session_id] = [s_tst].[session_id]
CROSS APPLY sys.dm_exec_sql_text ([s_ec].[most_recent_sql_handle]) AS [s_est]
OUTER APPLY sys.dm_exec_query_plan ([s_er].[plan_handle]) AS [s_eqp]
ORDER BY [BeginTime] ASC
```

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Error | 接続失敗時 | "Failure" - ConnectionError |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラーを記録し、次のインスタンスの処理を継続 |
| SQL Server 2005未満 | -MinimumVersion 9により接続段階で拒否 |
| オープントランザクションなし | 空の結果を返す（エラーにはならない） |

## 備考

- このコマンドはPaul Randalのオープントランザクション監視スクリプトに基づいています
- 参考: https://www.sqlskills.com/blogs/paul/script-open-transactions-with-text-and-plans/
- LastPlanはs_er.plan_handleがNULLの場合（現在実行中でない場合）はNULLになる可能性があります
- 結果はBeginTime昇順でソートされ、最も古いトランザクションが最初に表示されます

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とDMVから取得する情報の関係を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | 行37-54の.OUTPUTSセクションで出力プロパティを確認 |

**読解のコツ**: SERVERPROPERTY関数でサーバー情報を、DB_NAME関数でデータベース名を取得している点に注目。

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

クエリ定義と接続処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | 行69-75のパラメータ定義 |
| 2-2 | Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | 行78-113のSQLクエリ定義 |

**主要処理フロー**:
1. **行77**: beginブロックでSQLクエリを事前定義
2. **行78-113**: 複数DMVを結合する診断クエリ
3. **行117-121**: Connect-DbaInstance -MinimumVersion 9で接続

#### Step 3: クエリ実行と結果出力を理解する

クエリ実行と結果の直接出力を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | 行123のクエリ実行 |

**主要処理フロー**:
- **行123**: $server.Query($sql) - 結果は直接パイプラインに出力

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

```
Get-DbaOpenTransaction
    |
    +-- [beginブロック] SQLクエリ定義 (行78-113)
    |       └── 複数DMV結合クエリの構築
    |
    +-- Connect-DbaInstance (行118)
    |       └── SQL Serverへの接続（MinimumVersion 9）
    |
    └── $server.Query($sql) (行123)
            └── クエリ実行と結果出力
```

### データフロー図

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

SqlInstance ─────────────┐
                         │
SqlCredential ───────────┼──> Connect-DbaInstance
                         │          │
                         │          v
                         │   $server.Query($sql)
                         │          │
                         │          v
                         │   [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
                         │          │
                         │          v
                         └──> PSCustomObject
                              (オープントランザクション情報)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaOpenTransaction.ps1 | `public/Get-DbaOpenTransaction.ps1` | ソース | オープントランザクション取得の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
