# バッチ設計書 5-updateTeppAsync.ps1

## 概要

本ドキュメントは、dbatoolsモジュールのTEPPキャッシュを非同期で更新するバックグラウンドRunspaceスクリプト「updateTeppAsync.ps1」の設計仕様を記載したものである。

### 本バッチの処理概要

本スクリプトは、TabExpansion++（TEPP）機能で使用するタブ補完候補のキャッシュを非同期で更新するバックグラウンドRunspaceを管理する。SQL Serverインスタンスに接続して、データベース名、ログイン名、ジョブ名などのメタデータを取得し、TEPPキャッシュに格納する。これにより、ユーザーがタブ補完を使用する際に、最新のSQL Serverメタデータに基づいた候補が提示される。

**業務上の目的・背景**：dbatoolsモジュールのTEPP機能は、SQL Serverインスタンスから取得したメタデータに基づいてタブ補完候補を提示する。しかし、SQL Serverへの接続とメタデータ取得には時間がかかるため、メインスレッドで同期的に行うとユーザー体験が低下する。本スクリプトは、バックグラウンドRunspaceでSQL Serverに接続し、非同期でメタデータを取得・キャッシュすることで、タブ補完のレスポンスを高速に保ちながら、最新のメタデータを利用可能にする。優先度の高いサーバー（初回接続）と、定期更新対象のサーバーを区別して処理することで、効率的なキャッシュ更新を実現する。

**バッチの実行タイミング**：dbatoolsモジュールのインポート時に自動的に開始される。TEPP機能が無効化されていない場合にのみ動作する。15秒の初期遅延後に処理を開始し、5秒間隔でキャッシュ更新をポーリングする。

**主要な処理内容**：
1. 15秒の初期遅延でモジュールロード完了を待機
2. 優先サーバー（初回接続）のTEPPキャッシュ更新
3. 定期更新対象サーバーのTEPPキャッシュ更新
4. 各サーバーへのSMO接続とメタデータ取得
5. TeppGatherScriptsFastとTeppGatherScriptsSlowの実行

**前後の処理との関連**：本スクリプトはinsertTepp.ps1で登録されたTEPP補完機能と連携する。Connect-DbaInstanceコマンドでSQL Serverに接続すると、そのインスタンスがInstanceAccessに登録され、本スクリプトがキャッシュ更新の対象とする。

**影響範囲**：dbatoolsモジュールのタブ補完機能のパフォーマンスと精度に影響する。

## バッチ種別

バックグラウンドキャッシュ更新 / 非同期メタデータ取得

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | 継続的（5秒間隔でポーリング） |
| 実行時刻 | モジュールインポート後15秒で開始 |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | dbatoolsモジュールのインポート |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| dbatoolsモジュールのロード | dbatools.psm1が正常にインポートされていること |
| TEPP機能有効 | TeppAsyncDisabled, TeppDisabledがfalseであること |
| SQL Server接続履歴 | InstanceAccessにサーバー情報が登録されていること |

### 実行可否判定

TeppAsyncDisabledまたはTeppDisabledがtrueの場合、Runspaceは登録・開始されない。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 本スクリプトは直接パラメータを受け取らない |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| TabExpansionHost.InstanceAccess | Dictionary | 接続済みSQL Serverインスタンス情報 |
| TabExpansionHost.TeppGatherScriptsFast | ScriptBlock[] | 高速メタデータ取得スクリプト |
| TabExpansionHost.TeppGatherScriptsSlow | ScriptBlock[] | 低速メタデータ取得スクリプト |
| TabExpansionHost.TeppUpdateInterval | TimeSpan | キャッシュ更新間隔 |
| TabExpansionHost.TeppUpdateTimeout | TimeSpan | キャッシュ有効期限 |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| TEPPキャッシュ | 内部データ構造 | データベース名、ログイン名等のメタデータキャッシュ |

### 出力ファイル仕様

本スクリプトはファイル出力を行わない。

## 処理フロー

### 処理シーケンス

```
1. TEPP無効化チェック
   └─ TeppAsyncDisabled, TeppDisabledがtrueならスキップ
2. バックグラウンドRunspace用ScriptBlockの定義
3. 初期遅延（15秒）
   └─ モジュールロード完了を待機
4. dbatoolsモジュールのインポート
5. ヘルパー関数の定義
   ├─ Get-PriorityServer: 初回接続サーバーを取得
   ├─ Get-ActionableServer: 定期更新対象サーバーを取得
   └─ Update-TeppCache: キャッシュ更新処理
6. メインループ開始
   └─ while($true)で無限ループ
7. Runspace状態チェック
   └─ 状態が"Running"以外なら終了
8. 優先サーバーのキャッシュ更新
   └─ Get-PriorityServer | Update-TeppCache
9. 定期更新サーバーのキャッシュ更新
   └─ Get-ActionableServer | Update-TeppCache
10. スリープ
    └─ 5秒間待機後、次のサイクルへ
11. 終了処理
    └─ SignalStopped()でRunspaceの停止を通知
```

### フローチャート

```mermaid
flowchart TD
    A[スクリプト開始] --> B{TEPP無効?}
    B -->|Yes| Z[スクリプト終了]
    B -->|No| C[Runspace登録・開始]
    C --> D[15秒待機]
    D --> E[モジュールインポート]
    E --> F{Runspace状態確認}
    F -->|Running| G[優先サーバー取得]
    F -->|停止要求| L[終了処理]
    G --> H[キャッシュ更新]
    H --> I[定期更新サーバー取得]
    I --> J[キャッシュ更新]
    J --> K[5秒スリープ]
    K --> F
    L --> M[SignalStopped]
    M --> Z
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| メタデータ取得 | 各種システムビュー | SELECT | データベース名、ログイン名等のメタデータ取得 |

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

#### SQL Serverシステムビュー

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | 各種メタデータ | TeppGatherScriptsで定義 | SMO経由でアクセス |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Serverに接続できない | Write-Messageでログ出力後、次サーバーへ |
| - | メタデータ取得エラー | TeppGatherScript実行エラー | Write-Messageでログ出力後、次スクリプトへ |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 明示的なリトライなし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 次回ポーリングサイクルで自動的に再試行 |

### 障害時対応

接続エラーやメタデータ取得エラーはキャッチされ、ログ出力後に処理が継続される。致命的なエラーが発生した場合はfinallyブロックでSignalStopped()が呼び出される。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | 該当なし（SELECT操作のみ） |
| コミットタイミング | 該当なし |
| ロールバック条件 | 該当なし |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 接続済みSQL Serverインスタンス数に依存 |
| 目標処理時間 | TeppUpdateInterval以内 |
| メモリ使用量上限 | Runspace単位で数MB程度 |

## 排他制御

Runspaceは単一インスタンスで動作する。TeppUdaterStopperフラグにより、処理の中断を制御できる。各サーバーへの接続はシリアルに処理される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| デバッグログ | 接続エラー時 | 接続先サーバー、エラー詳細 |
| デバッグログ | メタデータ取得エラー時 | スクリプト名、サーバー名、エラー詳細 |
| デバッグログ | 致命的エラー時 | General Failure |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| Runspace状態 | Running以外 | 自動終了処理 |
| TeppUdaterStopper | true | 処理中断 |

## 備考

- 本スクリプトはprivate/scripts/配下に配置されている
- 15秒の初期遅延はモジュールロード完了を待つためのもの
- TeppGatherScriptsFastは高速なメタデータ取得（データベース名等）
- TeppGatherScriptsSlowは低速なメタデータ取得（詳細情報等）
- 優先サーバー：LastUpdateが1/1/1 1:1:1（初期値）のサーバー
- 定期更新対象：LastUpdateがTeppUpdateInterval以上経過し、TeppUpdateTimeout未満のサーバー
- 各接続後はDisconnect()で明示的に接続を解放
