# 機能設計書 553-Get-DbaDbRole

## 概要

本ドキュメントは、SQL Serverデータベースロールの取得機能について、その処理内容、入出力仕様、および実装詳細を記述した機能設計書である。

### 本機能の処理概要

Get-DbaDbRoleは、SQL Serverデータベースに定義されているデータベースロール（固定ロールおよびカスタムロール）を取得するPowerShellコマンドレットである。セキュリティ監査、権限分析、コンプライアンスレポート作成において、データベースレベルのロール構造を把握するために使用される。

**業務上の目的・背景**：SQL Serverでは、データベースロールを使用してユーザーの権限を効率的に管理する。db_owner、db_datareader、db_datawriterなどの固定ロールに加え、アプリケーション固有のカスタムロールが定義されることが多い。セキュリティ監査やマイグレーション時には、これらのロール構造を把握し、文書化することが重要である。本機能はこれらの要件に対応する。

**機能の利用シーン**：
- セキュリティ監査でのロール棚卸し
- 環境間のロール構成比較
- カスタムロールの識別と文書化
- マイグレーション前後のロール検証

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続（またはパイプライン入力の処理）
2. Get-DbaDatabaseを使用したデータベースコレクションの取得
3. 各データベースからRolesコレクションの取得
4. Role、ExcludeRole、ExcludeFixedRoleパラメータによるフィルタリング
5. 各ロールへのインスタンス情報の付与と出力

**関連システム・外部連携**：
- SMO（SQL Server Management Objects）使用
- Get-DbaDatabaseコマンドレットとの連携
- Get-DbaDbRoleMember（ロールメンバー取得）との連携

**権限による制御**：データベースロール情報の参照には、各データベースへのアクセス権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 37 | データベースロール管理 | 主画面 | データベースロールの取得 |

## 機能種別

データ取得（SELECT）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | No | 対象のSQL Serverインスタンス。パイプライン入力対応 | 有効なSQL Serverインスタンス名 |
| SqlCredential | PSCredential | No | 接続に使用する代替資格情報 | - |
| Database | string[] | No | 対象データベース名。ワイルドカード対応 | - |
| ExcludeDatabase | string[] | No | 除外するデータベース名。ワイルドカード対応 | - |
| Role | string[] | No | 取得するロール名。ワイルドカード対応 | - |
| ExcludeRole | string[] | No | 除外するロール名。ワイルドカード対応 | - |
| ExcludeFixedRole | switch | No | 固定ロールを除外 | - |
| InputObject | Database[] | No | パイプライン入力のデータベースオブジェクト | SMO Database型 |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SQL Serverインスタンス（Get-DbaDatabase経由）
- パイプライン入力（SMO Databaseオブジェクト）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverが稼働するコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | ロールが定義されているデータベース名 |
| Name | string | データベースロール名 |
| IsFixedRole | bool | 固定ロールかどうか |

### 出力先

- PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.Role型）

## 処理フロー

### 処理シーケンス

```
1. パラメータバインディング
   └─ SqlInstance、InputObject、フィルタ条件の受け取り

2. 入力検証
   └─ InputObjectとSqlInstanceの両方がない場合はエラー

3. データベースコレクション取得
   └─ SqlInstance指定時はGet-DbaDatabase経由
   └─ InputObject指定時は直接使用

4. foreach ($db in $InputObject) ループ
   └─ アクセス不可のDBはスキップ

5. ロールコレクション取得とフィルタリング
   └─ $db.Roles取得
   └─ Roleパラメータによる絞り込み
   └─ ExcludeRoleによる除外
   └─ ExcludeFixedRoleによる固定ロール除外

6. 結果の出力
   └─ Add-Memberでインスタンス情報追加
   └─ Select-DefaultViewで既定プロパティ選択
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject or SqlInstance?}
    B -->|Neither| C[Stop-Function: エラー]
    B -->|SqlInstance| D[Get-DbaDatabase]
    B -->|InputObject| E[InputObject使用]
    D --> F[InputObjectに追加]
    E --> F
    F --> G{各DBをループ}
    G --> H{IsAccessible?}
    H -->|No| I[スキップ]
    I --> G
    H -->|Yes| J[$db.Roles取得]
    J --> K{Roleフィルタ?}
    K -->|Yes| L[Name絞り込み]
    K -->|No| M{ExcludeRole?}
    L --> M
    M -->|Yes| N[Name除外]
    M -->|No| O{ExcludeFixedRole?}
    N --> O
    O -->|Yes| P[固定ロール除外]
    O -->|No| Q[結果ループ]
    P --> Q
    Q --> R[Add-Member: インスタンス情報]
    R --> S[Select-DefaultView]
    S --> G
    G -->|完了| T[終了]
    C --> T
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 入力必須 | SqlInstanceまたはInputObjectのいずれかが必要 | 常時 |
| BR-002 | アクセス可能DBのみ | IsAccessibleがfalseのDBはスキップ | 常時 |
| BR-003 | Roleフィルタ | Roleパラメータで名前が一致するロールのみ返却 | Role指定時 |
| BR-004 | ExcludeRoleフィルタ | ExcludeRoleで名前が一致するロールを除外 | ExcludeRole指定時 |
| BR-005 | 固定ロール除外 | IsFixedRole=falseかつpublic以外のロールのみ返却 | ExcludeFixedRole指定時 |

### 計算ロジック

固定ロール除外条件: `$_.IsFixedRole -eq $false -and $_.Name -ne 'public'`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ロール取得 | sys.database_principals | SELECT | SMO経由でDBロールを取得 |

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

#### sys.database_principals（SMO経由アクセス）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, principal_id, type等 | type='R'（ロール） | SMOのRolesコレクション経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | SqlInstanceもInputObjectも指定なし | Stop-Functionでメッセージ出力、処理終了 |

### リトライ仕様

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

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

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

## パフォーマンス要件

- Get-DbaDatabaseを経由するため、Database/ExcludeDatabaseでの絞り込みが有効
- 大量のデータベースがある場合はパイプライン処理を活用

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

- 各データベースへのアクセス権限が必要
- セキュリティ監査用途で使用される

## 備考

- Get-DbaDbRoleMemberと組み合わせてロールメンバーシップを確認可能
- publicロールはExcludeFixedRoleで除外される

---

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

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

### 推奨読解順序

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

SMO Roleオブジェクトの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | 出力型（.OUTPUTS）セクション（65-67行目） |

**読解のコツ**: DatabaseRoleはSMOのオブジェクトであり、IsFixedRole プロパティで固定ロールかカスタムロールかを判定できる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | function宣言とparamブロック（118-131行目） |

**主要処理フロー**:
1. **118-131行目**: パラメータ定義（SqlInstance、InputObject両方ValueFromPipeline）
2. **132行目**: processブロック開始
3. **133-136行目**: 入力検証

#### Step 3: データベース取得処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | Get-DbaDatabase呼び出し（138-140行目） |

**主要処理フロー**:
- **138-140行目**: SqlInstance指定時はGet-DbaDatabaseでデータベース取得
- **139行目**: Database、ExcludeDatabase、EnableExceptionパラメータをパススルー

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | ロールフィルタリング（149-158行目） |

**主要処理フロー**:
- **149行目**: $db.Rolesで全ロール取得
- **150-152行目**: Roleパラメータによる絞り込み
- **153-155行目**: ExcludeRoleによる除外
- **156-158行目**: ExcludeFixedRoleによる固定ロール/public除外

#### Step 5: 出力処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | 出力オブジェクト生成（160-166行目） |

**主要処理フロー**:
- **161-164行目**: Add-MemberでComputerName、InstanceName、SqlInstance、Database追加
- **165行目**: Select-DefaultViewで既定プロパティ選択

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

```
Get-DbaDbRole
    │
    ├─ Get-DbaDatabase
    │      └─ Connect-DbaInstance
    │             └─ SQL Server SMO接続
    │
    ├─ $db.Roles（各DBのロールコレクション）
    │      └─ Where-Object（フィルタリング）
    │
    ├─ Add-Member（プロパティ追加）
    │
    └─ Select-DefaultView（出力整形）
```

### データフロー図

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

SqlInstance ───▶ Get-DbaDatabase ───▶ Database[]
     or                 │
InputObject ────────────┘
                        │
                        ▼
              各 $db.Roles ───▶ フィルタリング
                        │
           ┌────────────┴────────────┐
           ▼            ▼            ▼
        Role        ExcludeRole   ExcludeFixedRole
                        │
                        ▼
              Add-Member ───▶ インスタンス情報付与
                        │
                        ▼
              Select-DefaultView ───▶ パイプライン出力
                                             │
                                             ▼
                                    Role Objects
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | ソース | メイン実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Get-DbaDbRoleMember.ps1 | `public/Get-DbaDbRoleMember.ps1` | ソース | ロールメンバー取得（関連機能） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
