# 機能設計書 88-Find-DbaDatabase

## 概要

本ドキュメントは、dbatools PowerShellモジュールのFind-DbaDatabase関数の機能設計を定義する。この関数は、複数のSQL Serverインスタンスから、名前、所有者、Service Broker GUIDのパターンに一致するデータベースを検索する機能を提供する。

### 本機能の処理概要

Find-DbaDatabase は、複数のSQL Serverインスタンスにわたってデータベースを検索し、特定の条件に一致するデータベースを発見するコマンドレットである。正規表現パターンによる柔軟な検索と、データベースサイズやオブジェクト数などの詳細情報を返す。

**業務上の目的・背景**：大規模なSQL Server環境では、開発、テスト、本番環境にまたがって多数のデータベースが存在する。特定のデータベースを環境横断で追跡したり、セキュリティ監査のために所有者別にデータベースを検索したり、データベース移行後にService Broker GUIDの一致を確認したりする際に、本機能が活用される。Service Broker GUIDは、ALTER DATABASE...NEW_BROKERを使用した復元やService Brokerの無効化時にリセットされることがあり、この問題の特定にも本機能が役立つ。

**機能の利用シーン**：
- 複数環境にわたる同名データベースの追跡
- セキュリティ監査のための所有者別データベース一覧作成
- データベース移行後のService Broker GUID確認
- 正規表現パターンによる柔軟なデータベース検索
- データベースインベントリの作成と比較

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続
2. 指定されたプロパティ（Name/Owner/ServiceBrokerGuid）でのフィルタリング
3. 正規表現または完全一致でのパターンマッチング
4. テーブル数、ビュー数、ストアドプロシージャ数の取得
5. 拡張プロパティの取得
6. 結果オブジェクトの出力

**関連システム・外部連携**：
- SQL Server Management Objects (SMO) を使用したデータベース情報取得
- sys.procedures, sys.tables, sys.views システムビューへのクエリ

**権限による制御**：
- 対象データベースへの接続権限が必要
- sys.procedures, sys.tables, sys.views への SELECT 権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | データベース管理 | 補助機能 | データベースの検索 |

## 機能種別

検索 / データベースインベントリ

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なPSCredentialオブジェクト |
| Property | string | No | 検索対象プロパティ | Name/ServiceBrokerGuid/Owner（デフォルト: Name） |
| Pattern | string | Yes | 検索パターン | 正規表現対応 |
| Exact | switch | No | 完全一致検索 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- パイプライン入力: SqlInstance をパイプラインから受け取り
- SQL Server: 各インスタンスのデータベースメタデータ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（サービス名） |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | データベース名 |
| Id | int | データベースID |
| Size | dbasize | データベースサイズ（MB） |
| Owner | string | データベース所有者 |
| CreateDate | DateTime | データベース作成日時 |
| ServiceBrokerGuid | Guid | Service Broker GUID |
| Tables | int | ユーザーテーブル数 |
| StoredProcedures | int | ユーザーストアドプロシージャ数 |
| Views | int | ユーザービュー数 |
| ExtendedProperties | object[] | 拡張プロパティ（Name, Value） |

### 出力先

- PowerShellパイプライン: PSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. SqlInstanceのループ処理
   └─ 各インスタンスへの接続確立（Connect-DbaInstance）

2. データベースフィルタリング
   ├─ アクセス可能なデータベースの取得
   ├─ Exact指定時: 完全一致でフィルター
   └─ 通常: 正規表現パターンでフィルター

3. 各データベースの処理
   ├─ 拡張プロパティの取得
   ├─ オブジェクト数クエリの実行
   └─ 結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[エラー出力、次へ]
    D -->|Yes| F[Databasesコレクション取得]
    F --> G[IsAccessibleでフィルター]
    G --> H{Exact?}
    H -->|Yes| I[プロパティ完全一致]
    H -->|No| J{正規表現マッチ成功?}
    J -->|No| K[ワイルドカード除去して再試行]
    J -->|Yes| L[マッチしたDBリスト]
    I --> L
    K --> L
    L --> M[各DBの処理ループ]
    M --> N[拡張プロパティ取得]
    N --> O[オブジェクト数クエリ実行]
    O --> P[結果オブジェクト出力]
    P --> Q{残りDB?}
    Q -->|Yes| M
    Q -->|No| R{残りInstance?}
    E --> R
    R -->|Yes| B
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | アクセス可能DBのみ | IsAccessible=trueのデータベースのみ対象 | 常時 |
| BR-002 | 正規表現検索 | Exact未指定時は正規表現パターンマッチング | Exact未指定時 |
| BR-003 | ワイルドカード自動除去 | 正規表現失敗時は*と%を除去して再試行 | 正規表現エラー時 |
| BR-004 | プロパティ指定 | Name/ServiceBrokerGuid/Ownerの3種類 | Property指定時 |

### 計算ロジック

- Size = db.Size * 1024 * 1024（バイトに変換後dbasize型で表示）
- Tables/StoredProcedures/Views: is_ms_shipped = 0でフィルターしてカウント

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| オブジェクト数取得 | sys.procedures | SELECT | ストアドプロシージャ数 |
| オブジェクト数取得 | sys.tables | SELECT | テーブル数 |
| オブジェクト数取得 | sys.views | SELECT | ビュー数 |

### テーブル別操作詳細

#### オブジェクト数クエリ

```sql
SELECT 'proc' AS t, COUNT(*) AS numFound FROM sys.procedures WHERE is_ms_shipped = 0
UNION ALL
SELECT 'tables' AS t, COUNT(*) AS numFound FROM sys.tables WHERE is_ms_shipped = 0
UNION ALL
SELECT 'views' AS t, COUNT(*) AS numFound FROM sys.views WHERE is_ms_shipped = 0
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverに接続できない | インスタンス名・認証情報を確認 |
| RegexError | パターンエラー | 無効な正規表現 | ワイルドカード除去後に再試行 |

### リトライ仕様

正規表現エラー時は、パターンから*と%を除去して自動的に再試行される。

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

読み取り専用操作のため、トランザクション制御は不要。

## パフォーマンス要件

- 各インスタンスへの接続に数秒かかる可能性あり
- 各データベースごとにオブジェクト数クエリを実行するため、データベース数に比例した時間がかかる

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

- SqlCredential パラメータで代替認証資格情報を安全に渡すことが可能
- 対象データベースへのアクセス権限が必要

## 備考

- Service Broker GUIDは、ALTER DATABASE...NEW_BROKERやService Broker無効化時にリセットされる
- 拡張プロパティがない場合、ExtendedPropertiesは0（数値）を返す

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Find-DbaDatabase.ps1 | `public/Find-DbaDatabase.ps1` | 139-153行目で出力オブジェクトの構造を確認 |

**読解のコツ**: dbasize型はサイズ表示を人間が読みやすい形式（KB/MB/GB）で自動フォーマットする。

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

パラメータ定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Find-DbaDatabase.ps1 | `public/Find-DbaDatabase.ps1` | 87-98行目のparam()ブロック |

**主要処理フロー**:
1. **89-90行目**: SqlInstanceパラメータ（Mandatory、パイプライン対応）
2. **92-93行目**: Propertyパラメータ（ValidateSet）
3. **94-95行目**: Patternパラメータ（Mandatory）
4. **96行目**: Exactスイッチ

#### Step 3: フィルタリング処理を理解する

データベースフィルタリングのロジックを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Find-DbaDatabase.ps1 | `public/Find-DbaDatabase.ps1` | 107-117行目のフィルタリング処理 |

**主要処理フロー**:
- **107-108行目**: Exact時の完全一致フィルター
- **110-111行目**: 正規表現マッチング
- **112-116行目**: 正規表現失敗時のワイルドカード除去と再試行

#### Step 4: 拡張プロパティとオブジェクト数の取得を理解する

追加情報の取得処理を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Find-DbaDatabase.ps1 | `public/Find-DbaDatabase.ps1` | 120-137行目の追加情報取得 |

**主要処理フロー**:
- **122-128行目**: 拡張プロパティのPSCustomObject配列作成
- **130行目**: 拡張プロパティがない場合は0を設定
- **132-137行目**: オブジェクト数クエリの実行

#### Step 5: 結果出力を理解する

最終的な出力オブジェクト構築を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Find-DbaDatabase.ps1 | `public/Find-DbaDatabase.ps1` | 139-153行目の結果出力 |

**主要処理フロー**:
- **139-153行目**: PSCustomObject作成と全プロパティの設定
- **145行目**: dbasize型へのキャスト（サイズの自動フォーマット）
- **149-151行目**: クエリ結果からオブジェクト数を抽出

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

```
Find-DbaDatabase
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続の確立
    │
    ├─ $server.Databases (SMO)
    │      └─ データベースコレクション取得
    │
    ├─ $db.ExtendedProperties (SMO)
    │      └─ 拡張プロパティ取得
    │
    └─ $db.Query()
           └─ オブジェクト数クエリ実行
```

### データフロー図

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

SqlInstance ───┬──▶ Connect-DbaInstance
               │           │
Property ──────┤           ▼
               │    Databases取得
Pattern ───────┤           │
               │           ▼
Exact ─────────┘    フィルタリング
                   (Exact/正規表現)
                          │
                          ▼
                   各DBの処理
                   ├─ 拡張プロパティ
                   └─ オブジェクト数クエリ
                          │
                          ▼
                   PSCustomObject ──────▶ パイプライン出力
                   (Name,Size,Owner,
                    Tables,Procs,Views...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Find-DbaDatabase.ps1 | `public/Find-DbaDatabase.ps1` | ソース | メイン関数定義 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得（関連機能） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ユーティリティ |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラーハンドリング関数 |
