# 機能設計書 121-Get-DbaEstimatedCompletionTime

## 概要

本ドキュメントは、SQL Serverインスタンスで実行中の長時間クエリの進捗状況と推定完了時間を監視するGet-DbaEstimatedCompletionTime機能の設計仕様を記載する。

### 本機能の処理概要

Get-DbaEstimatedCompletionTimeは、SQL Serverの動的管理ビュー`sys.dm_exec_requests`をクエリし、完了予定時間が利用可能な長時間実行中の操作のリアルタイム進捗情報を取得する機能である。

**業務上の目的・背景**：SQL Serverのメンテナンス作業やバックアップ・リストア処理は、データベースのサイズによっては数時間にわたることがある。DBAは、これらの操作がいつ完了するかを把握し、メンテナンスウィンドウ内で作業を完了できるかどうかを判断する必要がある。SQL Server Management Studioでは手動で確認が必要だが、本機能によりPowerShellから自動的かつプログラム的に進捗を監視できる。

**機能の利用シーン**：
- 定期メンテナンスウィンドウ中のバックアップ・リストア処理の監視
- 大規模データベースのDBCC CHECKDB実行状況の追跡
- インデックス再構築(ALTER INDEX REORGANIZE)の進捗確認
- TDE暗号化処理の完了時間見積もり
- ロールバック処理の所要時間予測

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続確立
2. sys.dm_exec_requestsとsys.dm_exec_sql_textをクエリし、estimated_completion_time > 0の操作を抽出
3. 経過時間、残り時間、完了予定時刻を計算してフォーマット
4. 結果をパイプライン経由で即座に出力

**関連システム・外部連携**：SQL Serverの動的管理ビュー(DMV)を使用。外部システムとの連携は不要。

**権限による制御**：VIEW SERVER STATEまたはVIEW DATABASE STATE権限が必要。sysadminロールのメンバーは全ての情報を取得可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コンソール/ターミナル | 主画面 | コマンド実行と結果表示 |

## 機能種別

データ取得(SELECT) / 監視・診断

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | ValueFromPipeline |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証対応 |
| Database | object[] | No | フィルタリング対象データベース名 | 複数指定・ワイルドカード可 |
| ExcludeDatabase | object[] | No | 除外するデータベース名 | 複数指定可 |
| EnableException | switch | No | 例外を直接スローするか | - |

### 入力データソース

- SQL Serverインスタンスへの接続パラメータ
- コマンドライン/パイプライン経由の入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名(コンピュータ\インスタンス) |
| Database | string | 操作が実行されているデータベース名 |
| Login | string | 操作を開始したログイン/ユーザー |
| Command | string | 実行中のコマンド(BACKUP, RESTORE, DBCC CHECKDBなど) |
| PercentComplete | decimal | 完了率(0-100) |
| StartTime | datetime | 操作開始日時 |
| RunningTime | string | 経過時間(HH:MM:SS形式) |
| EstimatedTimeToGo | string | 推定残り時間(HH:MM:SS形式) |
| EstimatedCompletionTime | datetime | 推定完了日時 |
| Text | string | 実行中のT-SQLクエリテキスト(デフォルト非表示) |

### 出力先

- PowerShellパイプライン(PSCustomObject)
- コンソール出力(Select-DefaultViewでTextプロパティを除外)

## 処理フロー

### 処理シーケンス

```
1. beginブロックでSQLクエリ文字列を初期化
   └─ sys.dm_exec_requestsとsys.dm_exec_sql_textを結合するクエリを構築

2. processブロックで各SqlInstanceをループ処理
   └─ Connect-DbaInstanceで接続確立

3. Databaseパラメータが指定された場合
   └─ WHERE句にDB_NAME(r.database_id) IN条件を追加

4. ExcludeDatabaseパラメータが指定された場合
   └─ WHERE句にDB_NAME(r.database_id) NOT IN条件を追加

5. SQLクエリを実行し結果を取得
   └─ $server.Query()メソッドで実行

6. 各行をPSCustomObjectに変換して出力
   └─ Select-DefaultViewでTextプロパティを除外
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ文字列初期化]
    B --> C{SqlInstanceループ}
    C -->|各インスタンス| D[Connect-DbaInstance接続]
    D --> E{Database指定?}
    E -->|Yes| F[IN条件追加]
    E -->|No| G{ExcludeDatabase指定?}
    F --> G
    G -->|Yes| H[NOT IN条件追加]
    G -->|No| I[クエリ実行]
    H --> I
    I --> J{結果行ループ}
    J -->|各行| K[PSCustomObject作成]
    K --> L[Select-DefaultViewで出力]
    L --> J
    J -->|終了| C
    C -->|全インスタンス完了| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 進捗情報取得条件 | estimated_completion_time > 0の操作のみ取得 | 全ての操作取得時 |
| BR-002 | 対象コマンド | ALTER INDEX REORGANIZE, BACKUP DATABASE, DBCC CHECKDB, RESTORE DATABASEなど進捗追跡可能な操作のみ | SQL Server仕様 |
| BR-003 | 時間フォーマット | 経過時間・残り時間はHH:MM:SS形式で表示 | 全ての時間表示 |

### 計算ロジック

- **RunningTime**: `DATEDIFF(s, start_time, GETDATE())`から時分秒を計算
- **EstimatedTimeToGo**: `estimated_completion_time`(ミリ秒)を時分秒に変換
- **EstimatedCompletionTime**: `DATEADD(SECOND, estimated_completion_time/1000, GETDATE())`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 進捗情報取得 | sys.dm_exec_requests | SELECT | 実行中リクエスト情報取得 |
| クエリテキスト取得 | sys.dm_exec_sql_text | SELECT | SQLテキスト取得 |

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

#### sys.dm_exec_requests

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | database_id, user_id, command, start_time, percent_complete, estimated_completion_time | WHERE estimated_completion_time > 0 | 進捗情報のある操作のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverインスタンスへの接続失敗 | Stop-Functionで警告出力後、次のインスタンスへ続行 |

### リトライ仕様

リトライ処理なし。接続失敗時は警告を出力して次のインスタンスの処理に移行。

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

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

## パフォーマンス要件

- DMVへの軽量クエリのため、通常は1秒以内に完了
- 複数インスタンス指定時は順次処理

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

- VIEW SERVER STATE権限が必要
- SqlCredentialによる認証情報の安全な受け渡し
- Windows認証、SQL認証、Active Directory認証に対応

## 備考

- 通常のSELECTクエリや短時間で完了する操作は結果に含まれない
- Textプロパティを表示するには`Select-Object *`を使用

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaEstimatedCompletionTime.ps1 | `public/Get-DbaEstimatedCompletionTime.ps1` | 関数の全体構造とパラメータ定義 |

**主要処理フロー**:
1. **119-147行目**: beginブロックでSQLクエリ文字列を構築
2. **149-155行目**: Connect-DbaInstanceでSQL Server接続
3. **157-165行目**: Database/ExcludeDatabaseパラメータによるクエリ条件追加
4. **168-183行目**: クエリ実行と結果のPSCustomObject変換

**読解のコツ**:
- SQL文字列内の時間計算ロジック(127-142行目)は複雑だが、時分秒の算出パターンを理解すれば読みやすい
- Select-DefaultView -ExcludeProperty Textにより、デフォルト出力からTextプロパティが除外される

#### Step 2: テストコードで動作を確認する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaEstimatedCompletionTime.Tests.ps1 | `tests/Get-DbaEstimatedCompletionTime.Tests.ps1` | 期待される動作とパラメータ検証 |

**主要処理フロー**:
- **9-23行目**: パラメータ検証テスト
- **75-101行目**: DBCC CHECKDBジョブを実行して進捗情報取得をテスト

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

```
Get-DbaEstimatedCompletionTime
    │
    ├─ Connect-DbaInstance (接続確立)
    │
    ├─ $server.Query() (SQLクエリ実行)
    │      └─ sys.dm_exec_requests + sys.dm_exec_sql_text
    │
    └─ Select-DefaultView (出力フォーマット)
```

### データフロー図

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

SqlInstance    ───▶  Connect-DbaInstance   ───▶
                           │
Database       ───▶  SQLクエリ構築         ───▶  sys.dm_exec_requests
                           │                      sys.dm_exec_sql_text
ExcludeDatabase ───▶  WHERE条件追加        ───▶       クエリ実行
                           │
                     PSCustomObject変換    ───▶  パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaEstimatedCompletionTime.ps1 | `public/Get-DbaEstimatedCompletionTime.ps1` | ソース | メイン関数定義 |
| Get-DbaEstimatedCompletionTime.Tests.ps1 | `tests/Get-DbaEstimatedCompletionTime.Tests.ps1` | テスト | 単体・統合テスト |
