# 画面設計書 90-インスタンス接続

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverインスタンス接続機能の設計仕様を定義する。SMO（SQL Server Management Object）接続オブジェクトを作成し、他のdbatools機能の基盤となるCLIを提供する。

### 本画面の処理概要

本機能は、SQL ServerインスタンスへのSMO接続を確立し、再利用可能なサーバーオブジェクトを返すためのコマンドラインインターフェースを提供する。Windows認証、SQL認証、Azure Active Directory認証をサポートし、接続プーリング、暗号化、フェイルオーバーパートナーなどの高度な接続オプションを提供する。

**業務上の目的・背景**：dbatools機能の大半はSQL Serverへの接続を必要とする。Connect-DbaInstanceは、これらの接続を一元管理し、一度確立した接続を複数のコマンドで再利用することでパフォーマンスと信頼性を向上させる。また、オンプレミス、Azure SQL Database、Azure SQL Managed Instanceなど、様々な環境への統一的な接続インターフェースを提供する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Connect-DbaInstance -SqlInstance <インスタンス名>`
- `$server = Connect-DbaInstance -SqlInstance <インスタンス名> -SqlCredential <認証情報>`
- `Connect-DbaInstance -SqlInstance <Azureインスタンス> -Database <DB名> -AccessToken <トークン>`

**主要な操作・処理内容**：
1. 認証方式の自動判定（Windows統合認証、SQL認証、Azure AD認証）
2. SMO Serverオブジェクトの作成と接続確立
3. 接続プーリングの管理
4. Azure SQL Database/Managed Instanceへの接続
5. 専用管理者接続（DAC）の確立
6. TEPP（Tab Expansion Plus Plus）キャッシュの更新

**画面遷移**：
- 出力先：他のすべてのdbatools機能（Get-DbaDatabase、Invoke-DbaQuery等）
- 関連：`Disconnect-DbaInstance`で明示的な切断

**権限による表示制御**：使用する認証方式に応じた適切な権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|-------------------|
| 127 | Connect-DbaInstance | 主機能 | SQL Server接続 |
| 174 | Disconnect-DbaInstance | 関連機能 | 接続切断 |
| 全機能 | - | 依存先 | ほぼすべてのdbatools機能がこの接続を使用 |

## 画面種別

コマンドラインインターフェース（CLI） / 接続・認証

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Connect-DbaInstance -SqlInstance <インスタンス名>`
- `Connect-DbaInstance -SqlInstance <インスタンス名> -SqlCredential <認証情報>`
- `Connect-DbaInstance -SqlInstance <インスタンス名> -Database <DB名>`
- `Connect-DbaInstance -SqlInstance <インスタンス名> -DedicatedAdminConnection`
- `Connect-DbaInstance -SqlInstance <Azureインスタンス> -AccessToken <トークン>`

## 入出力項目

### Connect-DbaInstance 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象インスタンス名または接続文字列 |
| SqlCredential | PSCredential | いいえ | SQL/Windows認証情報 |
| Database | string | いいえ | 初期データベース |
| ApplicationIntent | string | いいえ | ReadOnly/ReadWrite |
| BatchSeparator | string | いいえ | バッチ区切り文字（デフォルト：GO） |
| ClientName | string | いいえ | クライアント名 |
| ConnectTimeout | int | いいえ | 接続タイムアウト秒数 |
| EncryptConnection | switch | いいえ | SSL暗号化 |
| FailoverPartner | string | いいえ | フェイルオーバーパートナー |
| LockTimeout | int | いいえ | ロックタイムアウト秒数 |
| MaxPoolSize | int | いいえ | 最大プールサイズ |
| MinPoolSize | int | いいえ | 最小プールサイズ |
| MinimumVersion | int | いいえ | 最小SQL Serverバージョン |
| MultipleActiveResultSets | switch | いいえ | MARS有効化 |
| MultiSubnetFailover | switch | いいえ | マルチサブネットフェイルオーバー |
| NetworkProtocol | string | いいえ | ネットワークプロトコル |
| NonPooledConnection | switch | いいえ | プーリング無効化 |
| PacketSize | int | いいえ | パケットサイズ |
| PooledConnectionLifetime | int | いいえ | プール接続寿命 |
| SqlExecutionModes | string | いいえ | SQL実行モード |
| StatementTimeout | int | いいえ | ステートメントタイムアウト |
| TrustServerCertificate | switch | いいえ | サーバー証明書信頼 |
| AllowTrustServerCertificate | switch | いいえ | 証明書エラー時に再試行 |
| WorkstationId | string | いいえ | ワークステーションID |
| AlwaysEncrypted | switch | いいえ | Always Encrypted有効化 |
| AppendConnectionString | string | いいえ | 追加接続文字列 |
| SqlConnectionOnly | switch | いいえ | SqlConnectionのみ返す |
| AzureUnsupported | switch | いいえ | Azure非サポート宣言 |
| AzureDomain | string | いいえ | Azureドメイン |
| Tenant | string | いいえ | Azure ADテナントID |
| AccessToken | psobject | いいえ | アクセストークン |
| DedicatedAdminConnection | switch | いいえ | DAC接続 |
| DisableException | switch | いいえ | 例外を警告に変換 |

## 表示項目

### Connect-DbaInstance 出力オブジェクト（デフォルト）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| IsAzure | bool | Azure判定フラグ |
| DbaInstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| NetPort | int | TCPポート番号 |
| ConnectedAs | string | 接続ログイン名 |
| Databases | Collection | データベースコレクション |
| Logins | Collection | ログインコレクション |
| LinkedServers | Collection | リンクサーバーコレクション |
| Endpoints | Collection | エンドポイントコレクション |
| ConnectionContext | ServerConnection | 接続コンテキスト |
| VersionMajor | int | メジャーバージョン |
| VersionMinor | int | マイナーバージョン |
| Version | object | バージョンオブジェクト |
| DefaultFile | string | デフォルトデータファイルパス |
| DefaultLog | string | デフォルトログファイルパス |
| BackupDirectory | string | バックアップディレクトリ |
| Name | string | サーバー名 |
| DatabaseEngineType | string | エンジンタイプ |
| HostPlatform | string | プラットフォーム（Windows/Linux） |

### Connect-DbaInstance 出力オブジェクト（-SqlConnectionOnly指定時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| （SqlConnection） | Microsoft.Data.SqlClient.SqlConnection | SQL接続オブジェクト |

## イベント仕様

### 1-インスタンス接続（Connect-DbaInstance）

1. 入力オブジェクトタイプの判定（Server/SqlConnection/RegisteredServer/ConnectionString/String）
2. Azure判定（ドメイン名からAzure SQL Databaseを検出）
3. 認証方式の判定（integrated/ad/sql/token）
4. SqlConnectionInfoオブジェクトの構築
5. 接続パラメータの設定
6. ServerConnectionオブジェクトの作成
7. SMO Serverオブジェクトの作成
8. 接続テスト（SELECT 'dbatools is opening a new connection'）
9. AllowTrustServerCertificate時の証明書エラー再試行
10. AzureUnsupported/MinimumVersionチェック
11. NotePropertyの追加（ComputerName、IsAzure等）
12. TEPPキャッシュの更新
13. SetDefaultInitFieldsでSMO初期化フィールド設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Connect-DbaInstance | なし | - | 接続確立のみ（テスト用SELECT実行） |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------||
| MSG001 | エラー | The credential parameter was of a non-supported type. | 不正な認証情報タイプ |
| MSG002 | エラー | Failure | 接続エラー |
| MSG003 | 情報 | Initial connection failed due to certificate validation. Retrying with TrustServerCertificate enabled. | 証明書エラー時の再試行 |
| MSG004 | エラー | Azure SQL Database not supported | Azure非サポート機能での接続 |
| MSG005 | エラー | SQL Server version {version} required - {server} not supported. | バージョン非対応 |
| MSG006 | エラー | Failed to get access token for Azure SQL DB | アクセストークン取得失敗 |
| MSG007 | 警告 | Additional parameters are passed in, but they will be ignored | Server SMO再利用時のパラメータ無視 |
| MSG008 | エラー | Cannot use Windows credentials to connect when host is Linux or OS X. | Linux/macOSでのWindows認証 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 不正な認証情報タイプ | Stop-Functionでエラーを表示し処理を停止 |
| 接続エラー | Stop-Functionでエラーを表示（DisableException時は警告） |
| 証明書エラー（AllowTrustServerCertificate時） | TrustServerCertificateで再試行 |
| Azure非サポート機能 | 接続切断後Stop-Functionでエラーを表示 |
| バージョン非対応 | 接続切断後Stop-Functionでエラーを表示 |
| Linux/macOSでのWindows認証 | Stop-Functionでエラーを表示し処理を停止 |

## 備考

- 入力オブジェクトタイプ：
  - String：インスタンス名から新規接続
  - ConnectionString：接続文字列から接続
  - Server：既存SMOオブジェクトを再利用
  - SqlConnection：SqlConnectionからSMO作成
  - RegisteredServer：登録済みサーバーから接続
- 認証方式の自動判定：
  - ユーザー名に@またはバックスラッシュ含む → AD認証
  - ユーザー名のみ → SQL認証
  - AccessToken指定 → トークン認証
  - 認証情報なし → 統合認証
- SQL Serverバージョン番号：
  - 8 = SQL Server 2000
  - 9 = SQL Server 2005
  - 10 = SQL Server 2008
  - 11 = SQL Server 2012
  - 12 = SQL Server 2014
  - 13 = SQL Server 2016
  - 14 = SQL Server 2017
  - 15 = SQL Server 2019
  - 16 = SQL Server 2022
- DisableExceptionはConnect-DbaInstance固有の動作（他コマンドと逆の動作）
- 接続プーリングはデフォルトで有効
- DedicatedAdminConnectionは緊急用（接続後は明示的に切断必要）
- TEPPキャッシュ更新でタブ補完が有効になる

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 出力オブジェクトの構造（155-193行目）を確認 |

**読解のコツ**: 出力はMicrosoft.SqlServer.Management.Smo.ServerにNotePropertyを追加したもの（1177-1186行目）。SqlConnectionOnlyの場合はSqlConnectionObject。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | param()ブロック（349-388行目）で入力パラメータを確認 |

**主要処理フロー（beginブロック）**:
1. **389-409行目**: Invoke-TEPPCacheUpdate関数定義
2. **419-424行目**: 認証情報の型チェック
3. **427-433行目**: DisableException処理（他コマンドと逆の動作）
4. **449-456行目**: SMOバージョン別初期化フィールド定義

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

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

**入力タイプ別処理**:
- **591-595行目**: Server → 既存SMOオブジェクト再利用
- **596-600行目**: SqlConnection → SMO作成
- **601-607行目**: RegisteredServer → 接続文字列から接続
- **608-613行目**: ConnectionString → 接続文字列から接続
- **614-618行目**: String → インスタンス名から新規接続

#### Step 4: 認証処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 認証方式判定（776-805行目） |
| 4-2 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SqlConnectionInfo設定（807-968行目） |

**認証方式**:
- **776-781行目**: Azure判定
- **782-798行目**: AD認証判定（ユーザー名の形式から）
- **800-801行目**: トークン認証判定
- **802-804行目**: 統合認証（デフォルト）

#### Step 5: 接続確立を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 接続テスト（1072-1117行目） |

**主要処理フロー**:
- **1074-1078行目**: ExecuteWithResultsで接続テスト
- **1083-1111行目**: AllowTrustServerCertificate時の再試行ロジック
- **1119-1124行目**: AzureUnsupportedチェック
- **1126-1133行目**: MinimumVersionチェック

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

```
Connect-DbaInstance
    │
    ├─ begin ブロック
    │      ├─ Invoke-TEPPCacheUpdate 関数定義
    │      ├─ SqlCredential型チェック
    │      └─ SMO初期化フィールド定義
    │
    ├─ process ブロック
    │      │
    │      ├─ 入力タイプ判定
    │      │      ├─ Server → 既存SMO再利用
    │      │      ├─ SqlConnection → SMO作成
    │      │      ├─ RegisteredServer → 接続文字列から
    │      │      ├─ ConnectionString → 接続文字列から
    │      │      └─ String → 新規接続
    │      │
    │      ├─ 認証方式判定
    │      │      ├─ Azure判定
    │      │      ├─ AD/SQL/Token/Integrated判定
    │      │      └─ SqlConnectionInfo構築
    │      │
    │      ├─ ServerConnection作成
    │      │      ├─ AccessToken時: SqlConnection経由
    │      │      └─ 通常時: SqlConnectionInfo経由
    │      │
    │      ├─ SMO Server作成
    │      │
    │      ├─ 接続テスト
    │      │      ├─ ExecuteWithResults (SELECT)
    │      │      └─ AllowTrustServerCertificate再試行
    │      │
    │      ├─ チェック
    │      │      ├─ AzureUnsupported
    │      │      └─ MinimumVersion
    │      │
    │      ├─ NoteProperty追加
    │      │      ├─ ComputerName
    │      │      ├─ IsAzure
    │      │      ├─ DbaInstanceName
    │      │      ├─ SqlInstance
    │      │      ├─ NetPort
    │      │      └─ ConnectedAs
    │      │
    │      ├─ TEPPキャッシュ更新
    │      │
    │      └─ SetDefaultInitFields
    │
    └─ Server出力
```

### データフロー図

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

SqlInstance ─────▶ タイプ判定
      │                   │
      │         ┌─────────┼─────────┐
      │         │         │         │
      ▼         ▼         ▼         ▼
   String   Server  SqlConnection  ConnectionString
      │         │         │         │
      │         │         │         │
      └─────────┼─────────┼─────────┘
                │
                ▼
         認証方式判定
         (Azure/AD/SQL/Token/Integrated)
                │
SqlCredential ──┼──▶ SqlConnectionInfo
                │
AccessToken ────┼──▶ SqlConnection + AccessToken
                │
                ▼
         ServerConnection
                │
                ▼
         SMO Server
                │
                ▼
         接続テスト
         (SELECT 'dbatools is opening a new connection')
                │
         ┌──────┼──────┐
         │             │
         ▼             ▼
      成功         証明書エラー
         │             │
         │      AllowTrustServerCertificate?
         │             │
         │             ▼
         │      TrustServerCertificateで再試行
         │             │
         └──────┬──────┘
                │
                ▼
         AzureUnsupported / MinimumVersion チェック
                │
                ▼
         NoteProperty追加
         (ComputerName, IsAzure, SqlInstance, etc.)
                │
                ▼
         TEPPキャッシュ更新
                │
                ▼
         SetDefaultInitFields
                │
                ▼
         Microsoft.SqlServer.Management.Smo.Server
         (Extended)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Disconnect-DbaInstance.ps1 | `public/Disconnect-DbaInstance.ps1` | 関連 | 接続切断 |
| New-DbaAzAccessToken.ps1 | `public/New-DbaAzAccessToken.ps1` | 依存 | Azureアクセストークン生成 |
| Convert-ConnectionString.ps1 | `private/functions/Convert-ConnectionString.ps1` | 依存 | 接続文字列変換 |
| Hide-ConnectionString.ps1 | `private/functions/Hide-ConnectionString.ps1` | 依存 | 接続文字列マスキング |
| Add-ConnectionHashValue.ps1 | `private/functions/Add-ConnectionHashValue.ps1` | 依存 | 接続ハッシュ管理 |
