# 画面設計書 160-推定完了時間

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける推定完了時間監視機能の設計を定義する。sys.dm_exec_requestsを照会し、長時間実行中のSQL Server操作の進捗状況と推定完了時間をリアルタイムで取得する。

### 本画面の処理概要

本機能は、SQL Serverのメンテナンスや管理操作の進捗情報をリアルタイムで取得し、完了予測を提供する。完了率、実行時間、残り時間、推定完了時刻を表示する。

**業務上の目的・背景**：バックアップ、リストア、DBCC CHECKDBなどの長時間実行操作を監視する際、いつ完了するかを推測したり、SQL Server Management Studioで手動確認する必要がなくなる。特にメンテナンスウィンドウ中、大規模データベースのリストア時、パフォーマンス問題のトラブルシューティング時に、現在実行中の操作と残り時間を把握するのに有用である。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaEstimatedCompletionTime -SqlInstance <インスタンス名>`
- `Get-DbaEstimatedCompletionTime -SqlInstance <インスタンス名> -Database <データベース名>`

**主要な操作・処理内容**：
1. sys.dm_exec_requestsから推定完了時間のある操作を取得
2. sys.dm_exec_sql_textでクエリテキストを取得
3. 実行時間をHH:MM:SS形式でフォーマット
4. 残り時間をHH:MM:SS形式でフォーマット
5. 推定完了時刻を計算

**対象コマンド（完了率を表示）**：
- ALTER INDEX REORGANIZE
- AUTO_SHRINK option with ALTER DATABASE
- BACKUP DATABASE
- DBCC CHECKDB
- DBCC CHECKFILEGROUP
- DBCC CHECKTABLE
- DBCC INDEXDEFRAG
- DBCC SHRINKDATABASE
- DBCC SHRINKFILE
- RECOVERY
- RESTORE DATABASE
- ROLLBACK
- TDE ENCRYPTION

**画面遷移**：
- 本機能はスタンドアロンで動作し、他の機能への直接的な画面遷移はない
- パイプラインでWhere-Object等と連携可能

**権限による表示制御**：
- SQL Server接続権限が必要
- sys.dm_exec_requests への VIEW SERVER STATE 権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 409 | Get-DbaEstimatedCompletionTime | 主機能 | 推定完了時間の取得 |

## 画面種別

一覧 / 診断情報表示

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaEstimatedCompletionTime`

## 入出力項目

### Get-DbaEstimatedCompletionTime パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| Database | object[] | No | 対象データベース |
| ExcludeDatabase | object[] | No | 除外データベース |
| EnableException | switch | No | 例外処理の有効化 |

## 表示項目

### Get-DbaEstimatedCompletionTime 出力プロパティ

| プロパティ名 | 型 | 説明 | デフォルト表示 |
|-------------|------|------|---------------|
| ComputerName | string | コンピュータ名 | Yes |
| InstanceName | string | インスタンス名 | Yes |
| SqlInstance | string | 完全インスタンス名 | Yes |
| Database | string | データベース名 | Yes |
| Login | string | 操作を開始したログイン | Yes |
| Command | string | 実行中のコマンド（BACKUP, RESTORE, DBCC等） | Yes |
| PercentComplete | decimal | 完了率（0-100） | Yes |
| StartTime | datetime | 開始日時 | Yes |
| RunningTime | string | 経過時間（HH:MM:SS形式） | Yes |
| EstimatedTimeToGo | string | 残り時間（HH:MM:SS形式） | Yes |
| EstimatedCompletionTime | datetime | 推定完了日時 | Yes |
| Text | string | T-SQLクエリテキスト | No |

## イベント仕様

### 1-Get-DbaEstimatedCompletionTime実行

1. Connect-DbaInstanceでSQL Serverインスタンスに接続
2. sys.dm_exec_requestsに対するクエリを実行：
   - estimated_completion_time > 0 でフィルタ
   - CROSS APPLY sys.dm_exec_sql_text でクエリテキスト取得
3. Database/ExcludeDatabase でデータベースフィルタ適用
4. 経過時間と残り時間をHH:MM:SS形式に変換
5. 推定完了時刻を計算（DATEADD）
6. Select-DefaultViewでTextを非表示に設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaEstimatedCompletionTime | sys.dm_exec_requests | SELECT | 実行中リクエスト取得 |
| Get-DbaEstimatedCompletionTime | sys.dm_exec_sql_text | SELECT | SQLテキスト取得 |

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

本機能は読み取り専用のため、データベースへの更新は発生しない。

## メッセージ仕様

| メッセージID | レベル | 条件 | メッセージ内容 |
|-------------|--------|------|---------------|
| - | Debug | SQL実行時 | SQLクエリテキスト |
| - | Error | 接続失敗 | "Failure" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | ConnectionError カテゴリでStop-Function実行、処理継続 |

## 備考

- estimated_completion_time > 0 の操作のみが返される
- 通常のSELECTや短時間のクエリは結果に含まれない
- RunningTime/EstimatedTimeToGoはHH:MM:SS形式（時間が99時間を超える場合は桁数が増加）
- 参考資料:
  - https://blogs.sentryone.com/loriedwards/patience-dm-exec-requests/
  - https://docs.microsoft.com/en-us/sql/relational-databases/system-dynamic-management-views/sys-dm-exec-requests-transact-sql

---

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

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

### 推奨読解順序

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

推定完了時間情報のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaEstimatedCompletionTime.ps1 | `public/Get-DbaEstimatedCompletionTime.ps1` | 169-182行目: PSCustomObject出力構造 |

**読解のコツ**: RunningTimeとEstimatedTimeToGoはSQL Server側でフォーマット済み。Textはデフォルト非表示。

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

処理の起点となるコマンドレット関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaEstimatedCompletionTime.ps1 | `public/Get-DbaEstimatedCompletionTime.ps1` | 110-117行目: param()ブロック |

**主要処理フロー**:
1. **119-147行目**: beginブロックでSQLクエリ定義
2. **151-155行目**: Connect-DbaInstance
3. **157-165行目**: Database/ExcludeDatabase フィルタ
4. **168-183行目**: クエリ実行と結果出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaEstimatedCompletionTime.ps1 | `public/Get-DbaEstimatedCompletionTime.ps1` | 120-146行目: メインSQLクエリ |

**主要処理フロー**:
- **127-133行目**: RunningTime計算（DATEDIFF + 文字列フォーマット）
- **135-141行目**: EstimatedTimeToGo計算（estimated_completion_time + 文字列フォーマット）
- **142行目**: EstimatedCompletionTime計算（DATEADD）
- **146行目**: WHERE estimated_completion_time > 0

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

```
Get-DbaEstimatedCompletionTime
    |
    +-- begin
    |       +-- $sql クエリ定義
    |           +-- sys.dm_exec_requests
    |           +-- CROSS APPLY sys.dm_exec_sql_text
    |           +-- RunningTime 計算式
    |           +-- EstimatedTimeToGo 計算式
    |           +-- EstimatedCompletionTime 計算
    |           +-- WHERE estimated_completion_time > 0
    |
    +-- process
            |
            +-- foreach ($instance in $SqlInstance)
                    |
                    +-- Connect-DbaInstance
                    |
                    +-- [Database指定あり]
                    |       +-- AND DB_NAME(r.database_id) in (...)
                    |
                    +-- [ExcludeDatabase指定あり]
                    |       +-- AND DB_NAME(r.database_id) not in (...)
                    |
                    +-- Server.Query($sql)
                    |
                    +-- foreach ($row in results)
                            |
                            +-- PSCustomObject 作成
                            |
                            +-- Select-DefaultView -ExcludeProperty Text
```

### データフロー図

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

SqlInstance    ------>  Connect-DbaInstance  ----+
                                                 |
SqlCredential  ------>                           |
                                                 v
                                            sys.dm_exec_requests
                                            (WHERE estimated_completion_time > 0)
                                                 |
Database       ------>  IN句追加                 |
ExcludeDatabase -----> NOT IN句追加              |
                                                 v
                                            CROSS APPLY
                                            sys.dm_exec_sql_text
                                                 |
                                                 v
                                     +-------+-------+-------+
                                     |       |       |       |
                           RunningTime   ETG   ETC   Text
                           (HH:MM:SS)  (HH:MM:SS) (datetime)
                                     |       |       |       |
                                     +-------+-------+-------+
                                                 |
                                                 v
                                            PSCustomObject
                                                 |
                                                 v
                                            Select-DefaultView
                                            (Text非表示)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaEstimatedCompletionTime.ps1 | `public/Get-DbaEstimatedCompletionTime.ps1` | ソース | 推定完了時間取得の主処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
