# 非機能要件定義書

## 概要

本ドキュメントは、dbatools PowerShellモジュール（バージョン2.7.24）の非機能要件を定義するものである。dbatoolsは、SQL Server管理を自動化するためのPowerShellモジュールであり、約700のコマンドを提供している。本書では、コードベースの分析に基づき、性能、可用性、セキュリティ、拡張性、保守性、運用・監視の各観点から非機能要件を明確化する。

---

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 根拠・設定箇所 |
| --- | --- | --- |
| SQL接続タイムアウト | 15秒以内 | `sql.connection.timeout`設定（デフォルト値: 15） |
| SQL文実行タイムアウト | 無制限（0秒） | `sql.execution.timeout`設定（デフォルト値: 0 = 無制限） |
| CIM操作タイムアウト | 60秒以内 | `ComputerManagement.CimOperationTimeout`設定 |
| 不良接続再試行待機 | 15分 | `ComputerManagement.BadConnectionTimeout`設定 |
| PSセッション有効期限 | 5分 | `PSRemoting.Sessions.ExpirationTimeout`設定 |
| TEPP更新タイムアウト | 30秒 | `TabExpansion.UpdateTimeout`設定 |

### スループット

| 項目 | 目標値 | 根拠・設定箇所 |
| --- | --- | --- |
| ネットワークパケットサイズ | 4096バイト | `sql.connection.packetsize`設定 |
| 同時接続管理 | 接続プールによる最適化 | SMO接続プール機構を利用 |
| インメモリエラーレコード数 | 最大128件 | `Logging.MaxErrorCount`設定 |
| インメモリメッセージ数 | 最大1024件 | `Logging.MaxMessageCount`設定 |

### 大規模データ処理

| 項目 | 仕様 | 根拠 |
| --- | --- | --- |
| テラバイト級データベース移行 | 1時間以内 | README.mdでの性能特性説明 |
| バックアップテスト処理 | 1時間あたり1000件以上 | README.mdでの性能特性説明 |
| 複数インスタンス管理 | 100以上のSQLインスタンス | README.mdでの性能特性説明 |

---

## 可用性要件

| 項目 | 目標値 | 根拠・設定箇所 |
| --- | --- | --- |
| マルチサブネットフェイルオーバー | サポート | `sql.connection.multisubnetfailover`設定（デフォルト: false） |
| 接続再試行機構 | 不良接続15分間キャッシュ | `ComputerManagement.BadConnectionTimeout` |
| CIMセッション永続化 | 有効 | `ComputerManagement.Cache.Disable.CimPersistence`（デフォルト: false） |
| PSセッションキャッシュ | 有効 | `PSRemoting.Sessions.Enable`（デフォルト: true） |
| 資格情報自動登録 | 有効 | `ComputerManagement.Cache.Disable.CredentialAutoRegister`（デフォルト: false） |
| 資格情報フェイルオーバー | 設定可能 | `ComputerManagement.Cache.Enable.CredentialFailover`（デフォルト: false） |

### フォールトトレランス

| 機能 | 説明 |
| --- | --- |
| Always On可用性グループサポート | `ApplicationIntent`パラメータでReadOnlyルーティングをサポート |
| データベースミラーリング | `FailoverPartner`パラメータでフェイルオーバーパートナーを指定可能 |
| DAC接続 | `DedicatedAdminConnection`パラメータで緊急時管理者接続をサポート |
| 証明書検証フォールバック | `AllowTrustServerCertificate`で段階的なTLS検証を実装 |

---

## セキュリティ要件

### 認証・認可

| 要件 | 実装内容 | 根拠 |
| --- | --- | --- |
| Windows統合認証 | サポート | `Connect-DbaInstance`コマンドで自動検出 |
| SQL Server認証 | サポート | `SqlCredential`パラメータで指定 |
| Azure AD認証 | サポート | テナントID、アクセストークンによる認証 |
| サービスプリンシパル認証 | サポート | `azure.appid`、`azure.clientsecret`設定 |
| 証明書認証 | サポート | `azure.certificate.thumbprint`、`azure.certificate.store`設定 |

### 暗号化

| 要件 | 実装内容 | 根拠 |
| --- | --- | --- |
| 接続暗号化 | デフォルト有効 | `sql.connection.encrypt`設定（デフォルト: true） |
| サーバー証明書信頼 | デフォルト無効 | `sql.connection.trustcert`設定（デフォルト: false） |
| Always Encrypted | 設定可能 | `sql.alwaysencrypted.enable`設定 |
| エンクレーブ証明 | 設定可能 | `sql.alwaysencrypted.enclave`設定 |
| SSL/TLS（PSRemoting） | 設定可能 | `PSRemoting.PsSession.UseSSL`設定 |

### 資格情報管理

| 要件 | 実装内容 | 根拠 |
| --- | --- | --- |
| 不良資格情報キャッシュ | 再利用防止 | `ComputerManagement.Cache.Disable.BadCredentialList` |
| 資格情報のセキュアストレージ | SecureString使用 | `azure.clientsecret`のvalidation設定 |
| 厳格セキュリティモード | 設定可能 | `Import.StrictSecurityMode`設定 |

### ネットワークセキュリティ

| 要件 | 設定 |
| --- | --- |
| PSRemoting CA検証 | `PSRemoting.PsSessionOption.SkipCACheck`（デフォルト: false） |
| PSRemoting CN検証 | `PSRemoting.PsSessionOption.SkipCNCheck`（デフォルト: false） |
| 証明書失効検証 | `PSRemoting.PsSessionOption.SkipRevocationCheck`（デフォルト: false） |

---

## 拡張性要件

### プラットフォーム互換性

| プラットフォーム | サポート状況 | 制約 |
| --- | --- | --- |
| Windows 7/8/10/11 | 100%サポート | PowerShell v3以上 |
| Windows Server 2008 R2以降 | 100%サポート | PowerShell v3以上 |
| Linux (Intel/ARM64) | 78%サポート | PowerShell Core 7.4.0以上 |
| macOS (Intel/M1) | 78%サポート | PowerShell Core 7.4.0以上 |

### SQL Serverバージョン互換性

| SQLバージョン | サポート率 | 制約 |
| --- | --- | --- |
| SQL Server 2000 | 75% | 基本機能のみ |
| SQL Server 2005 | 90% | ほぼ全機能 |
| SQL Server 2008/R2 | 93% | ほぼ全機能 |
| SQL Server 2012以降 | 100% | 全機能 |
| Azure SQL Database | 40% | クラウド固有制限 |
| Azure SQL Managed Instance | 60% | クラウド固有制限 |

### モジュール依存関係

| 依存モジュール | バージョン | 用途 |
| --- | --- | --- |
| dbatools.library | 2025.12.28以上 | SMOライブラリ、コアDLL |
| .NET Framework | 4.6.2以上 | Windows PowerShell環境 |

### 設定拡張性

| 機能 | 説明 |
| --- | --- |
| 設定レジストリ | Windowsレジストリによる永続的設定管理 |
| 設定ファイル | JSON/XML形式での設定エクスポート・インポート |
| 環境変数 | `DBATOOLS_DISABLE_LOGGING`、`DBATOOLS_DISABLE_TEPP`等 |

---

## 保守性要件

### コーディング標準

| 要件 | 実装内容 |
| --- | --- |
| PowerShell v3互換性 | `::new()`構文の使用禁止、`New-Object`を使用 |
| OTBS形式 | One True Brace Styleの採用 |
| パラメータ命名 | PascalCase、単数形の強制 |
| 変数命名 | camelCase、読みやすい命名 |
| SMO優先 | T-SQLよりSMOを優先使用 |

### ドキュメント要件

| 要件 | 実装内容 |
| --- | --- |
| Comment-Based Help | 全コマンドに必須 |
| .OUTPUTS記述 | 型とプロパティの完全な文書化 |
| 例示コード | 動作確認済みの例を提供 |

### テスト要件

| 要件 | 実装内容 |
| --- | --- |
| Pesterテスト | 全コマンドに対するユニットテスト・統合テスト |
| AppVeyor CI | マルチシナリオでの自動テスト |
| コードカバレッジ | Codecovによる80%目標 |

---

## 運用・監視要件

### ロギング

| 設定項目 | デフォルト値 | 説明 |
| --- | --- | --- |
| メッセージログファイル有効 | true | `Logging.MessageLogFileEnabled` |
| エラーログファイル有効 | true | `Logging.ErrorLogFileEnabled` |
| 最大ログファイルサイズ | 5MB | `Logging.MaxMessagefileBytes` |
| 最大ログファイル数 | 5 | `Logging.MaxMessagefileCount` |
| 最大エラーファイルサイズ | 20MB | `Logging.MaxErrorFileBytes` |
| 最大フォルダサイズ | 100MB | `Logging.MaxTotalFolderSize` |
| ログファイル保持期間 | 7日 | `Logging.MaxLogFileAge` |

### ログ出力パス

| パス種別 | 設定 |
| --- | --- |
| ログ出力パス | `Path.DbatoolsLogPath`（AppData\PowerShell\dbatools） |
| データ保存パス | `Path.DbatoolsData`（AppData\PowerShell\dbatools） |
| 一時ファイルパス | `Path.DbatoolsTemp`（システム一時フォルダ） |
| エクスポートパス | `Path.DbatoolsExport`（Documents\DbatoolsExport） |

### 監視・診断

| 機能 | 説明 |
| --- | --- |
| クライアント名識別 | `sql.connection.clientname`でSQL Server監視ツールでの識別 |
| 接続追跡 | ApplicationNameによるProfiler/Extended Events追跡 |
| エラー履歴 | インメモリで最新128件のエラーを保持 |
| メッセージ履歴 | インメモリで最新1024件のメッセージを保持 |

### メンテナンス

| 機能 | 説明 |
| --- | --- |
| 自動ログクリーンアップ | 7日以上経過したログファイルの自動削除 |
| Runspace管理 | ISE終了時の自動クリーンアップ |
| 接続プールクリア | `Clear-DbaConnectionPool`コマンドで手動クリア可能 |

---

## 備考

### 環境変数による動作制御

| 環境変数 | 説明 |
| --- | --- |
| `DBATOOLS_DISABLE_LOGGING` | ファイルシステムへのログ記録を無効化 |
| `DBATOOLS_DISABLE_TEPP` | Tab Expansion Plus Plus機能を無効化 |

### 制約事項

1. **PowerShell ISEでのTranscript**: モジュールインポート前に`Start-Transcript`を実行する必要がある
2. **SqlServer/Azモジュールとの共存**: アセンブリ競合を回避するため、インポート順序に注意が必要
3. **Linux/macOSでの制限**: SQL WMIや`-ComputerName`パラメータを使用するコマンドは動作しない
4. **SQLSERVER:\ ドライブ**: このPSドライブからのモジュール読み込みは非サポート

### ネットワークポート要件

| プロトコル | デフォルトポート | 用途 | コマンド使用率 |
| --- | --- | --- | --- |
| SQL Database Engine | 1433 | データベース接続 | 62% |
| WS-Management | 5985/5986 | PowerShellリモーティング | 25% |
| SQL WMI | 135 | WMI/DCOM接続 | 4% |
| SMB | 445 | ファイル共有 | 4% |
