# 機能設計書 98-Get-DbaDatabase

## 概要

本ドキュメントは、SQL Serverインスタンスからデータベースオブジェクトとメタデータを取得するGet-DbaDatabase コマンドの機能設計書である。

### 本機能の処理概要

Get-DbaDatabase は、SQL Serverインスタンスから詳細なデータベース情報を取得し、基本的なメタデータクエリではなくリッチなデータベースオブジェクトを返却する機能である。データベースステータス、アクセスタイプ、リカバリモデル、バックアップ履歴、暗号化状態など、包括的なフィルタリングオプションを提供する。

**業務上の目的・背景**：データベースのインベントリ管理、コンプライアンス監査、メンテナンス計画において、データベースの詳細情報が必要となる。本機能はsys.databasesを直接クエリするのではなく、バックアップステータス、DMVからの使用統計、SQL Serverバージョン間で一貫した書式設定を含む完全なSMOデータベースオブジェクトを返却する。

**機能の利用シーン**：データベースインベントリの作成、バックアップポリシーのコンプライアンス確認、未使用データベースの特定（IncludeLastUsed）、TDE暗号化データベースの監査、特定のリカバリモデルを持つデータベースの検索、およびメンテナンスウィンドウの計画時に利用される。

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. 各種フィルタ条件に基づいてデータベースを抽出
3. オプションで最終使用情報（DMV）を取得
4. バックアップ履歴の確認（NoFullBackup/NoLogBackupオプション）
5. SMOデータベースオブジェクトにメタデータを付加して出力

**関連システム・外部連携**：SQL Server SMO（Databasesコレクション）、sys.databases、sys.dm_db_index_usage_stats DMV、msdbバックアップ履歴。

**権限による制御**：VIEW ANY DATABASE権限またはデータベースへのアクセス権限が必要。IncludeLastUsedオプションを使用する場合はVIEW DATABASE STATE権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | データベース管理 | 主機能 | データベースオブジェクトとメタデータの取得 |

## 機能種別

データ取得（SMO経由でのデータベースオブジェクト取得）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Database | String[] | No | 取得対象のデータベース名 | 完全一致 |
| ExcludeDatabase | String[] | No | 除外するデータベース名 | 完全一致 |
| Pattern | String[] | No | 正規表現パターンでフィルタ | .NET正規表現 |
| ExcludeUser | Switch | No | システムデータベースのみ取得 | ExcludeSystemと排他 |
| ExcludeSystem | Switch | No | ユーザーデータベースのみ取得 | ExcludeUserと排他 |
| Owner | String[] | No | 所有者でフィルタ | - |
| Encrypted | Switch | No | TDE有効データベースのみ | - |
| Status | String[] | No | ステータスでフィルタ | EmergencyMode, Normal等 |
| Access | String | No | アクセスモードでフィルタ | ReadOnly, ReadWrite |
| RecoveryModel | String[] | No | リカバリモデルでフィルタ | Full, Simple, BulkLogged |
| NoFullBackup | Switch | No | フルバックアップなしのみ | - |
| NoFullBackupSince | DateTime | No | 指定日時以降フルバックアップなし | - |
| NoLogBackup | Switch | No | ログバックアップなしのみ | - |
| NoLogBackupSince | DateTime | No | 指定日時以降ログバックアップなし | - |
| IncludeLastUsed | Switch | No | 最終使用日時を含める | - |
| OnlyAccessible | Switch | No | アクセス可能なDBのみ | - |
| EnableException | Switch | No | 例外処理を有効化 | - |

### 入力データソース

- SQL Server SMO Server.Databasesコレクション
- sys.databases（所有者、CDC状態）
- sys.dm_db_index_usage_stats（最終使用情報）
- msdbバックアップ履歴（Get-DbaDbBackupHistory経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverホストのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なSQL Serverインスタンス名 |
| Name | String | データベース名 |
| Status | String | データベースステータス |
| IsAccessible | Boolean | アクセス可能かどうか |
| RecoveryModel | String | リカバリモデル |
| LogReuseWaitStatus | String | ログ再利用待機ステータス |
| Size (SizeMB) | Decimal | データベースサイズ（MB） |
| Compatibility | Int32 | 互換性レベル |
| Collation | String | 照合順序 |
| Owner | String | 所有者 |
| Encrypted | Boolean | TDE有効かどうか |
| LastFullBackup | DateTime | 最終フルバックアップ日時 |
| LastDiffBackup | DateTime | 最終差分バックアップ日時 |
| LastLogBackup | DateTime | 最終ログバックアップ日時 |
| LastRead (オプション) | DateTime | 最終読み取り日時 |
| LastWrite (オプション) | DateTime | 最終書き込み日時 |
| BackupStatus (オプション) | String | バックアップステータス |
| IsCdcEnabled | Boolean | CDC有効かどうか |

### 出力先

PowerShellパイプラインに直接出力される

## 処理フロー

### 処理シーケンス

```
1. Begin処理：パラメータの排他チェック
   └─ ExcludeUserとExcludeSystemの同時指定を禁止
2. Process処理：各インスタンスに対してループ
   └─ Connect-DbaInstanceでSQL Serverに接続
3. 最終使用情報の取得（オプション）
   └─ dm_db_index_usage_statsからLastRead/LastWriteを取得
4. データベースのフィルタリング
   └─ 各種条件（Status, Access, Owner等）でフィルタ
5. バックアップ履歴の確認（オプション）
   └─ Get-DbaDbBackupHistoryでフルバックアップ/ログバックアップ履歴を取得
6. メタデータの付加と出力
   └─ Add-Memberでプロパティを追加、Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ExcludeUser AND ExcludeSystem?}
    B -->|Yes| C[Stop-Function]
    B -->|No| D{各SqlInstanceをループ}
    D --> E[Connect-DbaInstance]
    E --> F{IncludeLastUsed?}
    F -->|Yes| G[dm_db_index_usage_stats照会]
    F -->|No| H[データベースフィルタリング]
    G --> H
    H --> I{NoFullBackup/NoLogBackup?}
    I -->|Yes| J[Get-DbaDbBackupHistory]
    I -->|No| K[メタデータ付加]
    J --> K
    K --> L[Select-DefaultView出力]
    L --> D
    D -->|完了| M[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-98-1 | ExcludeUser/ExcludeSystem排他 | 両方同時指定は禁止 | パラメータバインド時 |
| BR-98-2 | OnlyAccessible最適化 | IsAccessible=trueのみ取得でSMO列挙高速化 | OnlyAccessible指定時 |
| BR-98-3 | パターンマッチング | 正規表現でデータベース名をフィルタ | Pattern指定時 |
| BR-98-4 | CopyOnlyバックアップの扱い | NoFullBackupでCopyOnlyのみの場合は「Only CopyOnly backups」 | NoFullBackup指定時 |
| BR-98-5 | サイズのフォールバック | SMO Sizeがnull/0の場合はT-SQLで取得 | 常時 |

### 計算ロジック

最終使用日時の計算：
```sql
LastRead = MAX(last_user_seek, last_user_scan, last_user_lookup)
LastWrite = MAX(last_user_update)
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| データベース情報取得 | sys.databases | SELECT | 基本情報取得 |
| 最終使用情報取得 | sys.dm_db_index_usage_stats | SELECT | アクセス統計取得 |
| サイズ取得 | sys.master_files / sys.database_files | SELECT | ファイルサイズ計算 |

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

#### sys.databases

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, state, owner_sid, is_cdc_enabled | 全データベース | SMO経由とT-SQL直接の両方 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionでエラー記録、次インスタンスに継続 |
| - | パラメータエラー | ExcludeUser+ExcludeSystem | Stop-Functionでメッセージ表示 |
| - | コレクション変更エラー | 処理中にDBが削除等 | エラーメッセージで対処方法を案内 |

### リトライ仕様

リトライ機構は実装されていない。

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

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

## パフォーマンス要件

- OnlyAccessibleオプションでSMO列挙を最適化
- SMO Sizeがnull/0の場合のみT-SQLフォールバック

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

- VIEW ANY DATABASE権限またはデータベースへのアクセス権限が必要
- SqlCredentialによる代替認証情報の使用をサポート
- TDE暗号化状態のレポートに対応

## 備考

- SQL Server 2000以降およびAzure SQL Databaseをサポート
- Azure SQL Databaseでは一部機能が制限される（sys.master_filesがない等）
- IncludeLastUsedのデータはSQL Server再起動でリセットされる

---

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

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

### 推奨読解順序

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

出力されるオブジェクトはSMOのDatabaseオブジェクトに追加プロパティを付与したものである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 177-212行目の.OUTPUTSセクション |

**読解のコツ**: Select-DefaultViewの$defaults配列で表示プロパティを確認。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 214-242行目のparam block |

**主要処理フロー**:
1. **214-242行目**: パラメータ定義（多数のフィルタオプション）
2. **244-250行目**: begin block（ExcludeUser/ExcludeSystemの排他チェック）
3. **251-538行目**: process block（メイン処理）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 303-312行目のDBTypeフィルタ |
| 3-2 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 367-412行目のWhere-Objectフィルタ |

**主要処理フロー**:
- **303-309行目**: ExcludeUser/ExcludeSystemによるDBType配列生成
- **367-373行目**: 事前フィルタ（T-SQL結果に対して）
- **399-412行目**: SMOオブジェクトに対するフィルタ

#### Step 4: バックアップ履歴処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | 413-431行目のバックアップ履歴処理 |

**主要処理フロー**:
- **413-424行目**: NoFullBackup/NoFullBackupSinceの処理
- **425-431行目**: NoLogBackup/NoLogBackupSinceの処理

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

```
Get-DbaDatabase
    │
    ├─ begin
    │      └─ パラメータ排他チェック
    │
    └─ process
           ├─ Connect-DbaInstance (接続確立)
           │
           ├─ Invoke-QueryDBlastUsed (オプション)
           │      └─ sys.dm_db_index_usage_stats照会
           │
           ├─ Invoke-QueryRawDatabases
           │      └─ sys.databases照会（Owner, CDC情報）
           │
           ├─ $server.Databases (SMOアクセス)
           │
           ├─ Get-DbaDbBackupHistory (オプション)
           │      └─ msdbバックアップ履歴
           │
           ├─ Invoke-QueryDatabaseSizes
           │      └─ sys.master_files/sys.database_files
           │
           └─ Select-DefaultView (出力整形)
```

### データフロー図

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

SqlInstance    ───▶ Connect-DbaInstance  ───▶ SMO Server
フィルタ条件               │
                           ▼
                    sys.databases照会
                    (Owner, CDC, State)
                           │
                           ▼
                    SMO Databases取得
                           │
                           ▼
                    フィルタリング
                    (Status, Access, etc.)
                           │
                           ▼
                    バックアップ履歴
                    (オプション)
                           │
                           ▼
                    メタデータ付加
                           │
                           ▼
              Select-DefaultView ───▶ Database オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
| Compare-DbaCollationSensitiveObject.ps1 | `private/functions/Compare-DbaCollationSensitiveObject.ps1` | ソース | 照合順序考慮の比較 |
