# 機能設計書 327-Connect-DbaInstance

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Connect-DbaInstance` 機能の設計書である。SQL Server Management Object（SMO）接続を作成し、ほぼすべてのdbatools操作の基盤となる接続オブジェクトを提供する。

### 本機能の処理概要

**業務上の目的・背景**：dbatoolsで実行されるすべてのSQL Server操作は、SMO接続を通じて行われる。各コマンドが個別に接続を確立するのではなく、永続的な接続オブジェクトを作成して再利用することで、接続オーバーヘッドを削減し、パフォーマンスを向上させる。本機能は、オンプレミス、Azure SQL Database、Always On可用性グループなど、様々な環境への接続を統一的なインターフェースで提供する。

**機能の利用シーン**：スクリプト実行前の接続確立、複数のSQL Server操作を実行する前の接続プール作成、Azure SQL Databaseへの認証、専用管理者接続（DAC）によるトラブルシューティング、読み取り専用セカンダリへのルーティングなどで利用される。

**主要な処理内容**：
1. 入力オブジェクトタイプの判別（文字列、接続文字列、SMO Server、SqlConnection等）
2. 認証方式の決定（Windows統合、SQL認証、Azure AD、アクセストークン等）
3. SqlConnectionInfoの設定
4. ServerConnectionおよびSMO Serverオブジェクトの作成
5. 接続テスト（SELECT実行）
6. 追加プロパティの付与（ComputerName、IsAzure等）
7. TEPP（Tab Expansion Plus Plus）キャッシュの更新
8. 接続ハッシュへの登録

**関連システム・外部連携**：
- SQL Server（オンプレミス、Azure SQL Database、Azure SQL Managed Instance）
- Azure Active Directory（Azure認証時）
- SQL Server Management Objects (SMO)

**権限による制御**：接続先インスタンスへのログイン権限が必要。Azure接続時は適切なAzure AD認証または資格情報が必要。

## 関連画面

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

## 機能種別

接続管理 / 認証処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス | パイプラインから受け取り可能 |
| SqlCredential | PSCredential | No | SQL認証用資格情報 | - |
| Database | string | No | 初期データベース | 設定から取得可能 |
| ApplicationIntent | string | No | アプリケーションインテント（ReadOnly/ReadWrite） | ValidateSet |
| BatchSeparator | string | No | バッチ区切り文字（デフォルト: GO） | - |
| ClientName | string | No | クライアントアプリケーション名 | 設定から取得可能 |
| ConnectTimeout | int | No | 接続タイムアウト秒数 | - |
| EncryptConnection | switch | No | SSL暗号化を強制 | - |
| FailoverPartner | string | No | ミラーリングフェイルオーバーパートナー | - |
| LockTimeout | int | No | ロックタイムアウト秒数 | - |
| MaxPoolSize | int | No | 接続プール最大サイズ | - |
| MinPoolSize | int | No | 接続プール最小サイズ | - |
| MinimumVersion | int | No | 最小SQL Serverバージョン | - |
| MultipleActiveResultSets | switch | No | MARS有効化 | - |
| MultiSubnetFailover | switch | No | マルチサブネットフェイルオーバー | - |
| NetworkProtocol | string | No | ネットワークプロトコル | ValidateSet |
| NonPooledConnection | switch | No | 非プール接続 | - |
| PacketSize | int | No | パケットサイズ | - |
| PooledConnectionLifetime | int | No | プール接続生存時間 | - |
| SqlExecutionModes | string | No | SQL実行モード | ValidateSet |
| StatementTimeout | int | No | ステートメントタイムアウト秒数 | - |
| TrustServerCertificate | switch | No | サーバー証明書を信頼 | - |
| AllowTrustServerCertificate | switch | No | 証明書エラー時にリトライ | - |
| WorkstationId | string | No | ワークステーションID | - |
| AlwaysEncrypted | switch | No | Always Encrypted有効化 | - |
| AppendConnectionString | string | No | 追加接続文字列パラメータ | - |
| SqlConnectionOnly | switch | No | SqlConnectionのみ返却 | - |
| AzureUnsupported | switch | No | Azure接続時にエラー | - |
| AzureDomain | string | No | Azureドメイン | - |
| Tenant | string | No | Azure ADテナントID | - |
| AccessToken | psobject | No | アクセストークン | - |
| DedicatedAdminConnection | switch | No | 専用管理者接続（DAC） | - |
| DisableException | switch | No | 例外を無効化（警告表示） | - |

### 入力データソース

- 文字列: サーバー名、接続文字列
- SMO Server: 既存のSMO接続オブジェクト
- SqlConnection: 既存のSQL接続
- RegisteredServer: 登録済みサーバー

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| (SMO Server) | Microsoft.SqlServer.Management.Smo.Server | SMO Serverオブジェクト |
| ComputerName | string | コンピュータ名（追加プロパティ） |
| IsAzure | bool | Azure接続フラグ（追加プロパティ） |
| DbaInstanceName | string | インスタンス名（追加プロパティ） |
| SqlInstance | string | 完全インスタンス名（追加プロパティ） |
| NetPort | int | TCPポート（追加プロパティ） |
| ConnectedAs | string | 接続ユーザー（追加プロパティ） |

SqlConnectionOnly指定時：
| 項目名 | 型 | 説明 |
|--------|-----|------|
| (SqlConnection) | Microsoft.Data.SqlClient.SqlConnection | SQL接続オブジェクト |

### 出力先

PowerShellパイプライン（SMO ServerオブジェクトまたはSqlConnection）

## 処理フロー

### 処理シーケンス

```
1. 入力オブジェクトタイプの判別
   └─ Server, SqlConnection, RegisteredServer, ConnectionString, Stringを識別
2. 認証方式の決定
   └─ azure/local + integrated/sql/ad/tokenを組み合わせ
3. SqlConnectionInfoの設定
   └─ 各パラメータをSqlConnectionInfoプロパティにマッピング
4. ServerConnectionの作成
   └─ アクセストークン使用時はSqlConnection経由
5. SMO Serverオブジェクトの作成
   └─ ServerConnectionからServerを作成
6. 接続テスト
   └─ SELECT文実行で接続確認
7. AllowTrustServerCertificate処理
   └─ 証明書エラー時にTrustServerCertificateでリトライ
8. バージョン・Azure チェック
   └─ MinimumVersion、AzureUnsupportedの検証
9. 追加プロパティの付与
   └─ ComputerName、IsAzure、SqlInstance等
10. TEPPキャッシュ更新
    └─ タブ補完用キャッシュの更新
11. 接続ハッシュへの登録
    └─ 接続プール管理用ハッシュに登録
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[入力オブジェクト<br>タイプ判別]
    B --> C{タイプ?}
    C -->|Server| D[既存接続を使用/コピー]
    C -->|SqlConnection| E[SqlConnectionから<br>Server作成]
    C -->|RegisteredServer/<br>ConnectionString| F[接続文字列から<br>SqlConnectionInfo作成]
    C -->|String| G[パラメータから<br>SqlConnectionInfo作成]
    D --> H[接続テスト]
    E --> H
    F --> H
    G --> H
    H --> I{接続成功?}
    I -->|No| J{AllowTrust<br>ServerCertificate?}
    J -->|Yes| K[TrustServerCertificate<br>でリトライ]
    J -->|No| L[エラー出力]
    K --> M{リトライ成功?}
    M -->|No| L
    M -->|Yes| N[続行]
    I -->|Yes| N
    N --> O{AzureUnsupported<br>かつAzure?}
    O -->|Yes| L
    O -->|No| P{MinimumVersion<br>チェック}
    P -->|失敗| L
    P -->|成功| Q{SqlConnectionOnly?}
    Q -->|Yes| R[SqlConnection返却]
    Q -->|No| S[追加プロパティ付与]
    S --> T[TEPPキャッシュ更新]
    T --> U[接続ハッシュ登録]
    U --> V[Server返却]
    R --> W[終了]
    V --> W
    L --> W
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-327-01 | 認証方式自動判定 | 資格情報タイプから認証方式を自動判定 | 常時 |
| BR-327-02 | Azure検出 | ドメイン名からAzure SQL Databaseを検出 | 接続時 |
| BR-327-03 | DAC接続 | 専用管理者接続時はADMIN:プレフィックス | DedicatedAdminConnection時 |
| BR-327-04 | 接続プール | デフォルトで接続プールを使用 | NonPooledConnection未指定時 |
| BR-327-05 | TEPP更新 | 新規接続時にタブ補完キャッシュを更新 | 新規接続時 |

### 計算ロジック

認証方式判定ロジック：
- Azure + SqlCredential（@含む）: azure ad
- Azure + SqlCredential（@含まない）: azure sql
- Azure + AccessToken: azure token
- Azure + なし: azure integrated
- Local + SqlCredential（\含む）: local ad
- Local + SqlCredential（\含まない）: local sql
- Local + なし: local integrated

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 接続テスト | - | SELECT | SELECT 'dbatools is opening a new connection' |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | CredentialError | 無効な資格情報タイプ | Stop-Functionでエラー出力 |
| - | ConnectionError | 接続失敗 | AllowTrustServerCertificateでリトライ or Stop-Function |
| - | AzureError | AzureUnsupportedでAzure接続 | Stop-Functionでエラー出力 |
| - | VersionError | MinimumVersionを満たさない | Stop-Functionでエラー出力 |
| - | PlatformError | Linux/macOSでWindows認証 | Stop-Functionでエラー出力 |

### リトライ仕様

AllowTrustServerCertificate指定時、証明書エラー（SSL/TLS/certificate/trust含む）でTrustServerCertificateを有効にしてリトライ。

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

接続のみで、トランザクション操作は行わない。接続プールはSMOによって管理される。

## パフォーマンス要件

- 接続プールによるパフォーマンス最適化
- SetDefaultInitFieldsによるSMO初期化の最適化
- TEPP更新はTeppSyncDisabled=falseの場合のみ

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

- Windows統合認証、SQL認証、Azure AD認証対応
- アクセストークン認証対応（Azure PowerShell v13/v14+両対応）
- TrustServerCertificateは開発環境向け、本番では非推奨
- 資格情報はPSCredentialオブジェクトとして安全に管理
- 接続文字列はHide-ConnectionStringでマスク

## 備考

- dbatools全体の基盤となる最重要関数
- 作者: Chrissy LeMaire (@cl)
- 詳細なリファレンス: https://dbatools.io/Connect-DbaInstance

---

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

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

### 推奨読解順序

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

追加プロパティと出力オブジェクトの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 155-192行目の.OUTPUTSセクション |
| 1-2 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 1180-1186行目の追加プロパティ付与 |

**読解のコツ**: Add-Memberで追加されるdbatools固有プロパティに注目。

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

パラメータ定義とbeginブロックを確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 347-388行目のparam定義 |
| 2-2 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 389-461行目のbeginブロック |

**主要処理フロー**:
- **347-388行目**: 多数のパラメータ定義（接続オプション全般）
- **419-424行目**: 資格情報検証
- **427-433行目**: DisableException処理
- **449-461行目**: SMOバージョン・フィールド定義

#### Step 3: 入力タイプ判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 591-619行目の入力タイプ判定 |

**主要処理フロー**:
- **591-595行目**: Serverタイプの判定
- **596-600行目**: SqlConnectionタイプの判定
- **601-607行目**: RegisteredServerタイプの判定
- **608-614行目**: ConnectionStringタイプの判定
- **614-619行目**: Stringタイプ（デフォルト）

#### Step 4: 認証方式と接続処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 776-805行目の認証方式決定 |
| 4-2 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 807-1019行目のSqlConnectionInfo設定 |
| 4-3 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 971-1019行目のアクセストークン処理 |

**主要処理フロー**:
- **776-805行目**: authType決定ロジック（azure/local + integrated/sql/ad/token）
- **807-808行目**: SqlConnectionInfo作成
- **971-1004行目**: アクセストークン処理（SecureString対応含む）
- **1015-1018行目**: ServerConnection・Server作成

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

```
Connect-DbaInstance
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ 設定値取得（接続パラメータのデフォルト値）
    │
    ├─ New-DbaAzAccessToken
    │      └─ Azure アクセストークン生成
    │
    ├─ SqlConnectionInfo (SMO)
    │      └─ 接続情報オブジェクト構築
    │
    ├─ ServerConnection (SMO)
    │      └─ サーバー接続オブジェクト構築
    │
    ├─ Server (SMO)
    │      └─ SMO Serverオブジェクト作成
    │
    ├─ ExecuteWithResults
    │      └─ 接続テスト実行
    │
    ├─ Add-ConnectionHashValue
    │      └─ 接続ハッシュ登録
    │
    └─ Invoke-TEPPCacheUpdate
           └─ タブ補完キャッシュ更新
```

### データフロー図

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

SqlInstance ───────▶ タイプ判定
    │                      │
    ├─ String             │
    ├─ ConnectionString   │
    ├─ RegisteredServer   │
    ├─ SqlConnection      │
    └─ Server             │
                          ▼
SqlCredential ─────▶ 認証方式決定
    or                    │
AccessToken               │
                          ▼
                   SqlConnectionInfo作成
                          │
                          ▼
                   ServerConnection作成
                          │
                          ▼
                   Server作成
                          │
                          ▼
                   接続テスト（SELECT）
                          │
                          ▼
                   追加プロパティ付与
                          │
                          ▼
                   Microsoft.SqlServer.Management.Smo.Server
                   （または SqlConnection）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | メイン関数の実装 |
| Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | ソース | 切断関数 |
| New-DbaAzAccessToken.ps1 | `public/New-DbaAzAccessToken.ps1` | ソース | Azureトークン生成 |
| Get-DbaConnectedInstance.ps1 | `public/Get-DbaConnectedInstance.ps1` | ソース | 接続済みインスタンス取得 |
