# 機能設計書 113-Get-DbaDbState

## 概要

本ドキュメントは、SQL Serverデータベースの状態情報（読み取り/書き込み状態、可用性、ユーザーアクセスモード）を取得するための機能設計書である。DBAsが頻繁に確認する必要がある3つの主要なデータベース状態プロパティを取得する。

### 本機能の処理概要

**業務上の目的・背景**：データベースの状態管理はSQL Server運用において基本的かつ重要な作業である。メンテナンス作業前の状態確認、問題発生時のトラブルシューティング、複数インスタンスにわたる状態監査など、様々な場面でデータベース状態の確認が必要となる。本機能は、sys.databasesから3つの主要な状態プロパティを効率的に取得し、運用作業を支援する。

**機能の利用シーン**：
- メンテナンス作業前のデータベース状態確認
- 接続問題のトラブルシューティング
- 複数インスタンスにわたるデータベース状態の監査
- SINGLE_USERモードに設定されたデータベースの検出
- READ_ONLYデータベースの特定

**主要な処理内容**：
1. 対象SQL Serverインスタンスへ接続
2. sys.databasesからデータベース状態情報を取得（SQL 2000用とSQL 2005以降用の2種類のクエリ）
3. システムデータベース（master、model、msdb、tempdb、distribution）を除外
4. 指定されたフィルタ条件（Database/ExcludeDatabase）を適用
5. 各データベースの状態情報をPSCustomObjectとして返却

**関連システム・外部連携**：sys.databases システムビューおよびDATABASEPROPERTYEX関数（SQL 2000用）を使用。

**権限による制御**：sys.databasesビューへの読み取り権限が必要（通常はpublicロールで付与される）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | PowerShellコマンドラインインターフェースのみ |

## 機能種別

データ参照（SELECT操作）/ 状態メトリクス取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス（パイプライン可） | 接続可能なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なWindows/SQL認証資格情報 |
| Database | object[] | No | 対象データベース名 | 存在するデータベース名 |
| ExcludeDatabase | object[] | No | 除外するデータベース名 | 存在するデータベース名 |
| EnableException | switch | No | 例外を発生させるかどうか | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー入力またはパイプライン（必須）
- Database/ExcludeDatabase: オプションのフィルタリング条件

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SqlInstance | string | SQL Serverインスタンス名（server.Name） |
| InstanceName | string | SQL Serverサービス名 |
| ComputerName | string | コンピュータ名 |
| DatabaseName | string | データベース名 |
| RW | string | 読み取り/書き込み状態（READ_WRITE / READ_ONLY） |
| Status | string | データベース状態（ONLINE / OFFLINE / EMERGENCY / RESTORING） |
| Access | string | ユーザーアクセスモード（SINGLE_USER / RESTRICTED_USER / MULTI_USER） |
| Database | SMO Database | SMO Databaseオブジェクト（非表示プロパティ） |

### 出力先

- PowerShellパイプライン（標準出力）
- PSCustomObject として返却（Select-DefaultViewでDatabaseプロパティを非表示）

## 処理フロー

### 処理シーケンス

```
1. beginブロック: SQLクエリの定義
   ├─ SQL 2005以降用クエリ（sys.databases直接クエリ）
   └─ SQL 2000用クエリ（DATABASEPROPERTYEX関数使用）
2. processブロック開始
   └─ 各SqlInstanceについてループ処理
      ├─ 2.1 Connect-DbaInstance で接続
      ├─ 2.2 バージョンに応じたクエリ実行
      ├─ 2.3 システムデータベースを除外
      ├─ 2.4 Database/ExcludeDatabase フィルタ適用
      ├─ 2.5 状態情報をハッシュテーブルに格納
      └─ 2.6 各データベースの結果を出力
3. エラー処理
   └─ 接続失敗時は Stop-Function で次のインスタンスへ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ定義]
    B --> C{SqlInstanceをループ}
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    F --> C
    E -->|Yes| G{SQL 2000?}
    G -->|Yes| H[SQL 2000用クエリ実行]
    G -->|No| I[SQL 2005+用クエリ実行]
    H --> J[システムDB除外]
    I --> J
    J --> K{Databaseフィルタ?}
    K -->|Yes| L[Databaseフィルタ適用]
    K -->|No| M{ExcludeDatabase?}
    L --> M
    M -->|Yes| N[ExcludeDatabase適用]
    M -->|No| O[ハッシュテーブル作成]
    N --> O
    O --> P{各DBをループ}
    P --> Q[PSCustomObject出力]
    Q --> P
    P --> C
    C --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムDB除外 | master、model、msdb、tempdb、distributionは除外 | 常時 |
| BR-002 | SQL 2000互換 | SQL Server 2000 はDATABASEPROPERTYEX関数を使用 | VersionMajor = 8 |
| BR-003 | 大文字小文字区別 | データベース名の比較は大文字小文字を区別する | ハッシュテーブル使用時 |

### 計算ロジック

- **RW**: sys.databases.is_read_only = 0 なら 'READ_WRITE'、1 なら 'READ_ONLY'
- **Status**: sys.databases.state_desc の値をそのまま使用
- **Access**: sys.databases.user_access_desc の値をそのまま使用

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 状態情報取得 | sys.databases | SELECT | データベース状態情報を取得 |

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

#### sys.databases (SQL 2005以降)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, user_access_desc, state_desc, is_read_only | 全件 | RWはCASE式で変換 |

#### DATABASEPROPERTYEX (SQL 2000)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name | 全件 | 関数で各プロパティを取得 |
| - | UserAccess | DATABASEPROPERTYEX(name, 'UserAccess') | ユーザーアクセスモード |
| - | Status | DATABASEPROPERTYEX(name, 'Status') | データベース状態 |
| - | Updateability | DATABASEPROPERTYEX(name, 'Updateability') | 読み取り/書き込み |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | Stop-Function でエラー出力、次のインスタンスへ |

### リトライ仕様

リトライ処理は実装されていない。接続エラー時は当該インスタンスをスキップして次を処理。

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

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

## パフォーマンス要件

- 各インスタンスに対して1回のクエリを実行
- sys.databasesは小さなシステムビューであり、高速に完了

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

- sys.databasesへの読み取り権限が必要
- SQL認証使用時は資格情報の安全な管理が必要

## 備考

- Set-DbaDbState 関数と組み合わせて使用することで、状態の確認と変更が可能
- SQL Server 2000からSQL Server 最新版まで対応
- 出力のDatabaseプロパティはSelect-DefaultViewで非表示だが、パイプライン処理で使用可能

---

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

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

### 推奨読解順序

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

本機能ではsys.databasesシステムビューを使用する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbState.ps1 | `public/Get-DbaDbState.ps1` | 出力がPSCustomObjectであることを確認（151-160行目） |

**読解のコツ**: Select-DefaultView で Databaseプロパティを非表示にしているが、パイプラインでは利用可能。

#### Step 2: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbState.ps1 | `public/Get-DbaDbState.ps1` | 2つのSQLクエリ定義（102-118行目） |

**主要処理フロー**:
1. **102-109行目**: SQL 2005以降用クエリ - sys.databases直接クエリ、is_read_onlyをCASEで変換
2. **111-118行目**: SQL 2000用クエリ - DATABASEPROPERTYEX関数を使用

#### Step 3: フィルタリングロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbState.ps1 | `public/Get-DbaDbState.ps1` | フィルタリングとハッシュテーブル処理（128-148行目） |

**主要処理フロー**:
- **128行目**: バージョンに応じたクエリ実行
- **133行目**: システムデータベースの除外
- **134-138行目**: Database/ExcludeDatabaseフィルタの適用
- **141-148行目**: ハッシュテーブルによる大文字小文字区別の対応

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

```
Get-DbaDbState
    │
    ├─ Connect-DbaInstance
    │
    └─ $server.Query()
           │
           └─ sys.databases クエリ
                  │
                  └─ Where-Object フィルタ
                         │
                         └─ PSCustomObject 構築
                                │
                                └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ $server
                            │
                            ▼
                     バージョン判定
                            │
              ┌─────────────┴─────────────┐
              ▼                           ▼
         SQL 2000                    SQL 2005+
         DATABASEPROPERTYEX          sys.databases
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                     システムDB除外
                            │
                            ▼
                     フィルタ適用
                            │
                            ▼
                     ハッシュテーブル
                            │
                            ▼
                     PSCustomObject ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbState.ps1 | `public/Get-DbaDbState.ps1` | ソース | メイン関数の実装 |
| Set-DbaDbState.ps1 | `public/Set-DbaDbState.ps1` | ソース | 関連機能：状態変更 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続機能 |
| Get-DbaDbState.Tests.ps1 | `tests/Get-DbaDbState.Tests.ps1` | テスト | 単体テスト |
