# 機能設計書 329-Disconnect-DbaInstance

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Disconnect-DbaInstance` 機能の設計書である。アクティブなSQL Server接続をクローズし、dbatools接続キャッシュから削除する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：dbatoolsで作成されたSQL Server接続は、接続プールによって管理される。長時間実行されるスクリプトや複数のインスタンスへの接続を行う場合、明示的に接続を閉じることで、接続リークを防ぎ、サーバー側の接続数制限を解放することが重要である。本機能は、Connect-DbaInstanceで作成した接続を適切にクローズし、内部の接続ハッシュから削除する。

**機能の利用シーン**：スクリプト終了時の接続クリーンアップ、専用管理者接続（DAC）使用後の切断、複数インスタンス処理後の接続解放、接続プール枯渇防止のための明示的切断などで利用される。

**主要な処理内容**：
1. 入力オブジェクトの判別（SMO Server、SqlConnection）
2. ConnectionContext.Disconnect()またはSqlConnection.Close()の実行
3. 接続ハッシュからのエントリ削除
4. 切断結果の返却

**関連システム・外部連携**：
- Connect-DbaInstance（接続作成元）
- Get-DbaConnectedInstance（接続一覧取得）
- Clear-DbaConnectionPool（接続プールクリア）

**権限による制御**：特別な権限は不要。接続オブジェクトへのアクセス権があれば実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | PowerShellコマンドラインからの実行 |

## 機能種別

接続管理 / リソース解放

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| InputObject | psobject[] | No | 切断する接続オブジェクト | パイプラインから受け取り可能 |
| EnableException | switch | No | 例外を有効化 | - |
| Confirm | switch | No | 確認プロンプト表示 | SupportsShouldProcess |
| WhatIf | switch | No | 実行内容の表示のみ | SupportsShouldProcess |

### 入力データソース

- SMO Server オブジェクト: Connect-DbaInstanceの戻り値
- SqlConnection オブジェクト: Connect-DbaInstance -SqlConnectionOnlyの戻り値
- Get-DbaConnectedInstance の出力オブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | 切断されたSQL Serverインスタンス名 |
| ConnectionString | string | マスクされた接続文字列 |
| ConnectionType | string | 接続オブジェクトの型名（完全修飾名） |
| State | string | 切断後の状態（Disconnected/Closed） |

### 出力先

PowerShellパイプライン（PSCustomObject、Select-DefaultViewで主要プロパティを表示）

## 処理フロー

### 処理シーケンス

```
1. processブロックでInputObjectを収集
   └─ パイプライン列挙問題を避けるため配列に追加
2. endブロックで各オブジェクトを処理
3. ConnectionObject プロパティがあれば展開
4. 各server/connectionに対してループ
5. ConnectionContextがある場合（SMO Server）
   └─ Disconnect()を実行
   └─ 接続ハッシュから削除
   └─ State=Disconnected で結果出力
6. SqlConnectionタイプの場合
   └─ Close()を実行（Openの場合のみ）
   └─ 接続ハッシュから削除
   └─ 現在のStateで結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[processブロック:<br>InputObjectを配列に収集]
    B --> C[endブロック:<br>各オブジェクトをループ]
    C --> D{ConnectionObject<br>プロパティあり?}
    D -->|Yes| E[ConnectionObjectを展開]
    D -->|No| F[InputObject使用]
    E --> G[各serverをループ]
    F --> G
    G --> H{ConnectionContext<br>あり?}
    H -->|Yes| I[Disconnect実行]
    I --> J{接続ハッシュに<br>エントリあり?}
    J -->|Yes| K[ハッシュから削除]
    J -->|No| L[続行]
    K --> L
    L --> M[結果オブジェクト出力<br>State=Disconnected]
    H -->|No| N{SqlConnection<br>タイプ?}
    N -->|Yes| O{State=Open?}
    O -->|Yes| P[Close実行]
    O -->|No| Q[スキップ]
    P --> R{接続ハッシュに<br>エントリあり?}
    Q --> R
    R -->|Yes| S[ハッシュから削除]
    R -->|No| T[続行]
    S --> T
    T --> U[結果オブジェクト出力<br>State=現在の状態]
    N -->|No| V[次のオブジェクト]
    M --> V
    U --> V
    V --> W{次のserver?}
    W -->|Yes| G
    W -->|No| X{次のobject?}
    X -->|Yes| C
    X -->|No| Y[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-329-01 | 接続ハッシュ削除 | 切断時に内部接続ハッシュからエントリ削除 | 常時 |
| BR-329-02 | パイプライン収集 | パイプライン列挙問題を避けるためprocessで収集してendで処理 | 常時 |
| BR-329-03 | オープン確認 | SqlConnectionはState=Openの場合のみClose | SqlConnection時 |
| BR-329-04 | 接続文字列マスク | 出力時に接続文字列をマスク | 常時 |

### 計算ロジック

特になし。

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

本機能はデータベース操作を行わない。接続のクローズのみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | DisconnectError | 切断処理失敗 | Stop-Functionで処理継続 |

### リトライ仕様

明示的なリトライ機能は実装されていない。

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

接続クローズのみで、トランザクション操作は行わない。

## パフォーマンス要件

特に定義されていない。即座に完了する軽量な操作。

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

- 接続文字列はHide-ConnectionStringでマスクして出力
- 特別な権限は不要

## 備考

- 対となる機能: Connect-DbaInstance
- 関連機能: Get-DbaConnectedInstance, Clear-DbaConnectionPool
- 作者: Chrissy LeMaire (@cl)

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | 92-97行目、111-116行目のPSCustomObject定義 |

**読解のコツ**: Select-DefaultViewでSqlInstance, ConnectionType, Stateが表示される。ConnectionStringは追加プロパティ。

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

パラメータ定義とprocess/endブロック構造を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | 66-71行目のparam定義 |
| 2-2 | Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | 72-75行目のprocessブロック |
| 2-3 | Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | 76-124行目のendブロック |

**主要処理フロー**:
- **66-71行目**: パラメータ定義（InputObjectはパイプライン対応）
- **72-75行目**: processでInputObjectを配列に収集
- **76-124行目**: endで実際の切断処理

#### Step 3: 切断処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | 84-98行目のSMO Server切断 |
| 3-2 | Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | 100-117行目のSqlConnection切断 |

**主要処理フロー**:
- **85-86行目**: ConnectionContextがあればDisconnect()
- **87-91行目**: 接続ハッシュからの削除
- **100-103行目**: SqlConnectionタイプでState=Openの場合Close()
- **105-109行目**: 接続ハッシュからの削除

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

```
Disconnect-DbaInstance
    │
    ├─ ConnectionContext.Disconnect()
    │      └─ SMO接続の切断
    │
    ├─ SqlConnection.Close()
    │      └─ SQL接続のクローズ
    │
    ├─ Hide-ConnectionString
    │      └─ 接続文字列のマスク
    │
    └─ $script:connectionhash.Remove()
           └─ 接続ハッシュからエントリ削除
```

### データフロー図

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

InputObject ────────▶ オブジェクトタイプ判定
    │                      │
    ├─ SMO Server         │
    │                      ▼
    │              ConnectionContext.Disconnect()
    │                      │
    └─ SqlConnection      │
                           ▼
                   SqlConnection.Close()
                           │
                           ▼
                   接続ハッシュ削除
                           │
                           ▼
                        PSCustomObject
                   （SqlInstance, ConnectionString,
                    ConnectionType, State）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | ソース | メイン関数の実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | 接続作成関数 |
| Get-DbaConnectedInstance.ps1 | `public/Get-DbaConnectedInstance.ps1` | ソース | 接続一覧取得 |
| Clear-DbaConnectionPool.ps1 | `public/Clear-DbaConnectionPool.ps1` | ソース | 接続プールクリア |
