# アーキテクチャ設計書

## 概要

本ドキュメントは、dbatoolsプロジェクトのアーキテクチャ設計を記述したものです。dbatoolsは、SQL Server管理を自動化するためのPowerShellモジュールであり、700近いコマンドを提供する大規模なオープンソースプロジェクトです。本設計書では、モジュールの構造、コンポーネント間の関係、設計パターン、および拡張ポイントについて詳細に説明します。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図.md](./アーキテクチャ構成図.md) を参照

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| SQL Server | SMO (SQL Server Management Objects) | データベース操作、サーバー管理、メタデータ取得 |
| SQL Server | T-SQL (ADO.NET) | クエリ実行、システムビュー/DMV参照 |
| dbatools.library | PowerShell依存モジュール | SMOライブラリ、コアライブラリ提供 |
| Windows Registry | レジストリアクセス | 設定の永続化 (Windows環境) |
| ファイルシステム | ファイルI/O | 設定ファイル、ログ、バックアップファイル |
| PowerShell Gallery | NuGet/HTTP | モジュール配布・更新 |
| Azure SQL Database | REST API / SMO | Azure SQL管理 |
| Azure Active Directory | OAuth/MSAL | Azure認証 |

## レイヤー構成

### アーキテクチャスタイル

dbatoolsは **モジュラーモノリス** アーキテクチャを採用しています。PowerShellモジュールとして単一のパッケージで配布されますが、内部は機能別に明確に分離されたモジュール構造を持っています。

主要な設計思想:
- **コマンドベースアーキテクチャ**: 各機能は独立したPowerShell関数（コマンドレット）として実装
- **パイプライン指向**: PowerShellパイプラインを活用したデータフロー設計
- **SMOファースト**: SQL Server Management Objects (SMO) を優先的に使用
- **クロスプラットフォーム**: Windows/Linux/macOS対応

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Public Functions | ユーザー向けコマンド提供、パラメータ処理、出力フォーマット | `public/*.ps1` (約700コマンド) |
| Private Functions | 内部ユーティリティ、共通処理、ヘルパー関数 | `private/functions/*.ps1` (約125関数) |
| Configuration | 設定管理、永続化、バリデーション | `private/configurations/` |
| Scripts | バックグラウンド処理、TEPP、ロギング | `private/scripts/` |
| Library | .NETクラス、型定義、コアロジック | `dbatools.library` (外部モジュール) |
| Testing | Pesterテスト、CI/CD統合 | `private/testing/` |

### レイヤー間の依存関係ルール

```
+------------------+
|  Public Functions | ← ユーザーからのエントリポイント
+------------------+
         |
         v
+------------------+
| Private Functions | ← 内部ロジック
+------------------+
         |
         v
+------------------+
|  Configuration   | ← 設定・状態管理
+------------------+
         |
         v
+------------------+
|    Library       | ← .NETコアライブラリ (dbatools.library)
+------------------+
         |
         v
+------------------+
|   SMO / SQL      | ← SQL Server接続
+------------------+
```

**依存の方向性**:
- Public Functions は Private Functions を呼び出し可能
- Private Functions は Configuration を参照可能
- すべての層は Library (dbatools.library) を参照可能
- Private Functions 間の相互呼び出しは許可
- Public Functions 間の直接呼び出しは避け、パイプラインを使用

**禁止される参照**:
- Library から Public/Private Functions への参照
- Configuration から Public Functions への参照

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール/コマンドプレフィックス |
| --- | --- | --- |
| インスタンス管理 | SQL Serverインスタンスの接続・管理 | `Connect-DbaInstance`, `Get-DbaInstance*` |
| データベース管理 | データベース操作全般 | `*-DbaDb*`, `*-DbaDatabase` |
| バックアップ/リストア | バックアップ・リストア操作 | `Backup-Dba*`, `Restore-Dba*` |
| エージェント | SQL Server Agent管理 | `*-DbaAgent*` |
| 可用性グループ | Always On AG管理 | `*-DbaAg*`, `*-DbaAvailabilityGroup` |
| セキュリティ | ログイン・権限管理 | `*-DbaLogin`, `*-DbaCredential`, `*-DbaRole*` |
| レプリケーション | レプリケーション設定 | `*-DbaRepl*` |
| 拡張イベント | XE管理 | `*-DbaXE*` |
| 診断 | パフォーマンス分析・監視 | `Get-DbaWait*`, `Invoke-DbaDiagnostic*` |
| マイグレーション | サーバー間移行 | `Copy-Dba*`, `Start-DbaMigration` |
| 設定管理 | モジュール設定 | `*-DbatoolsConfig` |

### パッケージ構造

```
dbatools/
├── dbatools.psd1                    # モジュールマニフェスト
├── dbatools.psm1                    # モジュールローダー
├── public/                          # 公開コマンド (約700ファイル)
│   ├── Add-DbaAgDatabase.ps1
│   ├── Backup-DbaDatabase.ps1
│   ├── Connect-DbaInstance.ps1
│   └── ... (約700コマンド)
├── private/                         # 内部モジュール
│   ├── functions/                   # 内部ヘルパー関数 (約125ファイル)
│   │   ├── Add-ConnectionHashValue.ps1
│   │   ├── Convert-*.ps1
│   │   ├── Get-*.ps1
│   │   └── ...
│   ├── configurations/              # 設定システム
│   │   ├── configuration.ps1        # 設定システムコア
│   │   ├── settings/                # 設定ファイル群
│   │   └── validation/              # バリデーションルール
│   ├── dynamicparams/               # 動的パラメータ定義
│   ├── scripts/                     # バックグラウンドスクリプト
│   │   ├── insertTepp.ps1           # TEPPキャッシュ
│   │   ├── logfilescript.ps1        # ロギング
│   │   ├── updateTeppAsync.ps1      # 非同期TEPP更新
│   │   └── dbatools-maintenance.ps1 # メンテナンス処理
│   ├── testing/                     # テストユーティリティ
│   └── maintenance/                 # メンテナンススクリプト
├── opt/                             # オプショナルコマンド (PowerShell v5未満用)
├── bin/                             # バイナリ/リソースファイル
│   ├── typealiases.ps1              # 型エイリアス定義
│   ├── XEtemplates/                 # 拡張イベントテンプレート
│   ├── diagnosticquery/             # 診断クエリ
│   ├── maintenancesolution/         # メンテナンスソリューション
│   ├── datamasking/                 # データマスキング設定
│   └── perfmontemplates/            # パフォーマンス監視テンプレート
├── xml/                             # 型・フォーマット定義
│   ├── dbatools.Types.ps1xml        # 型拡張
│   └── dbatools.Format.ps1xml       # 出力フォーマット
├── en-us/                           # ヘルプドキュメント
├── tests/                           # Pesterテスト (約730ファイル)
└── docs/                            # ドキュメント
```

### コンポーネント依存関係

**モジュールローダー (dbatools.psm1) の役割**:
1. dbatools.library モジュールの読み込み
2. .NET アセンブリのインポート
3. 型エイリアスの登録
4. Private/Public 関数のドットソーシング
5. 設定システムの初期化
6. TEPPとロギングのバックグラウンド処理開始
7. エイリアスの登録

**コマンド間の依存パターン**:
- `Connect-DbaInstance`: ほぼ全コマンドが依存する中核コンポーネント
- `Write-Message`: ログ出力の統一インターフェース
- `Test-Bound`: パラメータバインディングの検証
- `Stop-Function`: エラーハンドリングの統一

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | SQL Server | 2000 - 2025 | 管理対象データベース |
| RDB | Azure SQL Database | - | クラウドデータベース管理 |
| RDB | Azure SQL Managed Instance | - | マネージドインスタンス管理 |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| インメモリキャッシュ | PowerShellランタイム | 接続プール、TEPPキャッシュ | セッション中 |
| 静的変数 | - | $script:connectionhash (接続キャッシュ) | モジュール読み込み中 |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| PowerShell Runspace | .NET | 非同期ログ処理、TEPP更新 |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| N/A | - | 検索エンジンは使用していません |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| SMO (SQL Server Management Objects) | SQL Server バージョンに依存 | SQL Server管理API |
| ADO.NET (Microsoft.Data.SqlClient) | 最新 | SQLクエリ実行 |
| MSAL (Microsoft Authentication Library) | - | Azure AD認証 |

## データフロー

### リクエスト処理の流れ

1. **ユーザーコマンド入力**: PowerShellコンソールからコマンドを実行
2. **パラメータバインディング**: PowerShellランタイムがパラメータを解析
3. **Begin ブロック**: 初期化処理、接続確立
4. **Process ブロック**: パイプライン入力の処理
   - `Connect-DbaInstance` によるSMO接続取得
   - SMOオブジェクトまたはT-SQLによるデータ取得
   - 結果オブジェクトの構築
5. **End ブロック**: クリーンアップ処理
6. **パイプライン出力**: PSCustomObjectまたはSMOオブジェクトの出力

### 非同期処理の流れ

1. **TEPPキャッシュ更新** (Tab Expansion Plus Plus):
   - バックグラウンドRunspaceで非同期実行
   - データベース名、ログイン名などの補完候補を更新
   - `private/scripts/updateTeppAsync.ps1` で実装

2. **ロギング**:
   - 別Runspaceでログファイルへの書き込みを非同期実行
   - メイン処理をブロックしない設計
   - `private/scripts/logfilescript.ps1` で実装

3. **メンテナンス処理**:
   - 古いログファイルの削除
   - キャッシュの整理
   - `private/scripts/dbatools-maintenance.ps1` で実装

### データ永続化の流れ

1. **設定の保存**:
   - `Set-DbatoolsConfig` でメモリ上の設定を変更
   - `Register-DbatoolsConfig` で永続化
   - Windows: レジストリに保存
   - Linux/macOS: JSONファイルに保存

2. **接続情報の管理**:
   - `$script:connectionhash` で接続をキャッシュ
   - セッション終了時に自動クリア
   - `Disconnect-DbaInstance` で明示的クリア

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| Windows統合認証 | Connect-DbaInstance | オンプレミスSQL Server |
| SQL Server認証 | Connect-DbaInstance (SqlCredential) | SQL Server全般 |
| Azure AD認証 | Connect-DbaInstance (Tenant, AccessToken) | Azure SQL |
| サービスプリンシパル | New-DbaAzAccessToken | Azure自動化 |
| マネージドID | New-DbaAzAccessToken | Azure VM/App Service |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | Write-Message関数 | `$script:path_Logging` (ファイル) |
| デバッグログ | Write-Message -Level Debug | コンソール/ファイル |
| パフォーマンスログ | Write-ImportTime | インポート時間計測 |
| エラーログ | Stop-Function, Write-Message -Level Warning | コンソール/ファイル |

### エラーハンドリング

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| 接続エラー | try/catch + Stop-Function | エラーメッセージ出力、EnableException時は例外スロー |
| パラメータエラー | Stop-Function | エラーメッセージ出力 |
| SQL実行エラー | try/catch + Write-Message | 警告/エラーメッセージ |
| 権限エラー | Stop-Function | スキップ + 警告 |

**EnableExceptionパターン**:
- `-EnableException` スイッチでエラー時の挙動を制御
- `$false` (デフォルト): 警告を出力して処理続行
- `$true`: 例外をスローして処理中断

### トランザクション管理

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| 単一コマンド | SMOトランザクション / T-SQL BEGIN TRAN | SMOデフォルト |
| バッチ処理 | 各コマンドで個別管理 | コマンド依存 |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 単一責任原則 (SRP) | 各コマンドは1つの責務 | `Get-DbaDatabase` はデータベース取得のみ |
| 開放閉鎖原則 (OCP) | パイプライン拡張 | 出力オブジェクトにカスタムプロパティ追加可能 |
| インターフェース分離 | 共通パラメータセット | `-SqlInstance`, `-SqlCredential`, `-EnableException` |
| DRY | Private Functions | 共通ロジックはヘルパー関数に集約 |
| KISS | シンプルなコマンド設計 | 1コマンド = 1機能 |

### コーディング規約

**命名規則**:
- コマンド名: `<Verb>-Dba<Noun>` (承認された動詞のみ使用)
- 名詞は単数形: `Get-DbaDatabase` (not `Get-DbaDatabases`)
- パラメータ: PascalCase (`$SqlInstance`, `$EnableException`)
- 変数: camelCase (`$currentLogin`, `$dbLogin`)

**パラメータ標準**:
- `$SqlInstance`: 対象SQL Serverインスタンス
- `$SqlCredential`: 認証情報
- `$EnableException`: エラー時に例外をスロー
- `$WhatIf`, `$Confirm`: 破壊的操作のサポート

**出力規則**:
- パイプラインへの即時出力 (配列に貯めない)
- `[PSCustomObject]` での統一的な出力形式
- `ComputerName`, `InstanceName`, `SqlInstance` プロパティの一貫性

**禁止事項**:
- バッククォート (`) による行継続
- `= $true` 構文 (Parameter属性内)
- `::new()` 構文 (PowerShell v3互換性のため)
- 結果のArrayListへの蓄積

## 備考

### バージョン互換性

- **PowerShell**: v3+ (Windows), v7.4.0+ (Core/Linux/macOS)
- **SQL Server**: 2000 - 2025 (機能により異なる)
- **.NET Framework**: 4.6.2+ (Windows Desktop)
- **.NET Core**: dbatools.library経由

### 外部依存モジュール

| モジュール | バージョン | 用途 |
| --- | --- | --- |
| dbatools.library | 2025.12.28+ | コアライブラリ、SMO |

### CI/CD構成

- **CI**: AppVeyor (Pesterテスト)
- **シナリオ**: SINGLE, MULTI, COPY, HADR, RESTART, 2008R2SP2Express
- **コードカバレッジ**: Codecov

### 拡張ポイント

1. **新規コマンドの追加**: `public/` に新規 `.ps1` ファイルを作成し、`dbatools.psd1` と `dbatools.psm1` に登録
2. **設定の追加**: `private/configurations/settings/` に設定ファイルを追加
3. **型拡張**: `xml/dbatools.Types.ps1xml` でカスタム型メンバーを追加
4. **出力フォーマット**: `xml/dbatools.Format.ps1xml` でカスタムビューを定義
5. **テンプレート**: `bin/` ディレクトリにXE/診断クエリ/メンテナンスソリューションのテンプレートを追加
