# 画面設計書 37-データベースロール管理

## 概要

本ドキュメントは、dbatoolsにおけるデータベースロール管理機能の設計仕様を定義する。

### 本画面の処理概要

データベースロール管理機能は、SQL Serverのデータベースロールの取得・作成を行うPowerShellコマンド群を提供する。データベースロールはデータベースレベルの権限グループであり、ユーザーの権限管理を効率化するために使用される。

**業務上の目的・背景**：データベースロールは、データベース内の権限をグループ化して管理するための仕組みである。固定データベースロール（db_owner、db_datareader等）と、カスタムのユーザー定義ロールが存在する。本機能は、セキュリティ監査、権限分析、複数データベース間での一貫したロール構成の維持を支援する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする。
- `Get-DbaDbRole` - データベースロールの取得
- `New-DbaDbRole` - データベースロールの作成

**主要な操作・処理内容**：
1. データベースロールの取得：固定ロール・カスタムロールの一覧と詳細情報の取得
2. データベースロールの作成：新規カスタムロールの作成

**画面遷移**：本機能はCLIベースのため画面遷移は存在しないが、以下のコマンド間で連携が可能。
- `Get-DbaDatabase` から `Get-DbaDbRole` または `New-DbaDbRole` へパイプライン入力
- セキュリティ監査ワークフローでの権限分析

**権限による表示制御**：ロールの作成にはデータベースのCREATE ROLE権限またはdb_securityadmin固定データベースロールのメンバーシップが必要。ロールの参照にはデータベースへのアクセス権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 189 | Get-DbaDbRole | 主機能 | データベースロールの取得 |
| 201 | New-DbaDbRole | 主機能 | データベースロールの作成 |

## 画面種別

CLI（コマンドラインインターフェース）- PowerShellコマンド

## URL/ルーティング

N/A（PowerShellモジュールのコマンドとして提供）

## 入出力項目

### Get-DbaDbRole

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstance[] | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | string[] | - | 対象データベース名フィルター |
| ExcludeDatabase | string[] | - | 除外データベース名 |
| Role | string[] | - | 取得対象ロール名フィルター |
| ExcludeRole | string[] | - | 除外ロール名 |
| ExcludeFixedRole | switch | - | 固定ロールを除外 |
| InputObject | Database[] | - | パイプライン入力用データベースオブジェクト |
| EnableException | switch | - | 例外処理の有効化 |

### New-DbaDbRole

| 項目名 | 型 | 必須 | 説明 |
|--------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | - | 代替認証情報 |
| Database | string[] | - | 対象データベース名 |
| ExcludeDatabase | string[] | - | 除外データベース名 |
| Role | String[] | 必須 | 作成するロール名 |
| Owner | String | - | ロールの所有者（デフォルト：dbo） |
| InputObject | Database[] | - | パイプライン入力用データベースオブジェクト |
| EnableException | switch | - | 例外処理の有効化 |

## 表示項目

### Get-DbaDbRole 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| Database | string | データベース名 |
| Name | string | ロール名 |
| IsFixedRole | bool | 固定ロールフラグ |

### Get-DbaDbRole 追加プロパティ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Owner | string | ロールの所有者 |
| CreateDate | DateTime | ロール作成日時 |
| DateLastModified | DateTime | 最終更新日時 |
| ID | int | ロールのオブジェクトID |
| Urn | string | URN識別子 |

### New-DbaDbRole 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLインスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| Name | string | ロール名 |
| Parent | string | 親データベース名 |
| Owner | string | ロールの所有者 |

## イベント仕様

### 1-データベースロール取得

Get-DbaDbRoleコマンド実行時：
1. InputObjectまたはSqlInstanceの指定を確認
2. SqlInstance指定時はGet-DbaDatabaseでデータベースを取得
3. アクセス不可なデータベースはスキップ
4. データベースのRolesコレクションを取得
5. Roleパラメータでフィルタリング
6. ExcludeRoleパラメータで除外
7. ExcludeFixedRole指定時は固定ロールとpublicロールを除外
8. カスタムプロパティ（ComputerName、InstanceName等）を追加して出力

### 2-データベースロール作成

New-DbaDbRoleコマンド実行時：
1. InputObjectまたはSqlInstanceの指定を確認
2. Roleパラメータの指定を確認（必須）
3. SqlInstance指定時はGet-DbaDatabaseでデータベースを取得
4. アクセス可能なデータベースのみを対象
5. 既存ロールとの重複を確認
6. ShouldProcess確認（-Confirmまたは-WhatIf対応）
7. New-Object DatabaseRoleでロールオブジェクトを作成
8. Owner指定がない場合はデフォルトで"dbo"を設定
9. Create()メソッドでロールを作成
10. カスタムプロパティを追加して出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| データベースロール取得 | sys.database_principals | SELECT | ロール情報の参照 |
| データベースロール作成 | sys.database_principals | INSERT | 新規ロールの作成 |

### ロール作成詳細

```sql
-- SMO内部で生成されるSQL
CREATE ROLE [RoleName] AUTHORIZATION [Owner]
```

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|--------------|----------|
| MSG001 | エラー | You must pipe in a database or specify a SqlInstance | SqlInstanceとInputObject両方未指定 |
| MSG002 | エラー | You must specify a new role name. | Role未指定（New-DbaDbRole） |
| MSG003 | エラー | The {role} role already exist within database {db} on instance {server}. | 同名ロールが既に存在 |
| MSG004 | 詳細 | Getting Database Roles for {db} on {server} | ロール取得処理開始 |
| MSG005 | 詳細 | Add roles to Database {db} on target {server} | ロール追加処理開始 |
| MSG006 | 確認 | Creating new DatabaseRole {role} on database {db} | ロール作成確認 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SqlInstanceとInputObject両方未指定 | Stop-Functionでエラー出力して終了 |
| Role未指定（New-DbaDbRole） | Stop-Functionでエラー出力して終了 |
| データベースにアクセスできない | スキップして続行 |
| 同名ロールが既に存在 | Stop-Functionでエラー出力して続行 |
| ロール作成失敗 | Stop-Functionでエラー出力して続行 |

## 備考

- 固定データベースロールには以下が含まれる：
  - db_owner: データベースの完全な管理権限
  - db_securityadmin: ロールメンバーシップと権限の管理
  - db_accessadmin: ユーザーのアクセス管理
  - db_backupoperator: バックアップ実行権限
  - db_ddladmin: DDLコマンドの実行権限
  - db_datawriter: データの追加・変更・削除権限
  - db_datareader: データの読み取り権限
  - db_denydatawriter: データ書き込みの拒否
  - db_denydatareader: データ読み取りの拒否
- publicロールは全ユーザーが自動的にメンバーとなる特殊ロール
- カスタムロールのデフォルト所有者は"dbo"
- ロール作成後、Add-DbaDbRoleMemberでメンバーを追加可能

---

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

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

### 推奨読解順序

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

データベースロール管理で扱う主要なデータ構造はSMOのRoleオブジェクト（またはDatabaseRole）である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | 出力オブジェクトの構造（行65-84）を確認 |

**読解のコツ**: RoleオブジェクトのIsFixedRoleプロパティが固定ロールとカスタムロールを区別する重要なプロパティ。

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

各コマンドのprocess{}ブロックが処理の起点となる。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | 行132-168のprocessブロック |
| 2-2 | New-DbaDbRole.ps1 | `public/New-DbaDbRole.ps1` | 行103-162のprocessブロック |

**主要処理フロー（Get-DbaDbRole）**:
1. **行133-136**: InputObjectまたはSqlInstanceの必須確認
2. **行138-140**: Get-DbaDatabaseでデータベース取得
3. **行143-145**: アクセス不可なデータベースをスキップ
4. **行149-158**: フィルタリング処理
5. **行160-166**: カスタムプロパティ追加と出力

#### Step 3: ロール作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbRole.ps1 | `public/New-DbaDbRole.ps1` | パラメータ検証（行104-112） |
| 3-2 | New-DbaDbRole.ps1 | `public/New-DbaDbRole.ps1` | 重複チェック（行129-131） |
| 3-3 | New-DbaDbRole.ps1 | `public/New-DbaDbRole.ps1` | ロール作成（行136-154） |

**主要処理フロー（New-DbaDbRole）**:
- **行109-112**: Roleパラメータの必須チェック
- **行120**: アクセス可能なデータベースのみフィルタリング
- **行129-131**: 同名ロールの存在チェック
- **行137-145**: DatabaseRoleオブジェクト作成とプロパティ設定
- **行147**: Create()メソッドでロール作成

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

```
Get-DbaDbRole
    |
    +-- Get-DbaDatabase
    |
    +-- Database.Roles (SMOコレクション)
    |
    +-- フィルタリング (Role/ExcludeRole/ExcludeFixedRole)
    |
    +-- Select-DefaultView (出力整形)

New-DbaDbRole
    |
    +-- Get-DbaDatabase
    |
    +-- Database.Roles (重複チェック)
    |
    +-- New-Object DatabaseRole
    |
    +-- DatabaseRole.Create()
    |
    +-- Select-DefaultView (出力整形)
```

### データフロー図

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

SqlInstance    ----->  Connect-DbaInstance
                            |
Database       ----->  フィルタリング           ----->  対象データベース
                            |
                     Database.Roles取得
                            |
Role           ----->  名前フィルタリング
                            |
ExcludeRole    ----->  除外フィルタリング
                            |
ExcludeFixedRole ---->  固定ロール除外
                            |
                     Select-DefaultView          ----->  Role (ロール情報)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbRole.ps1 | `public/Get-DbaDbRole.ps1` | ソース | データベースロール取得コマンド |
| New-DbaDbRole.ps1 | `public/New-DbaDbRole.ps1` | ソース | データベースロール作成コマンド |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得（依存コマンド） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続（依存コマンド） |
| Add-DbaDbRoleMember.ps1 | `public/Add-DbaDbRoleMember.ps1` | ソース | ロールメンバー追加（関連コマンド） |
| Remove-DbaDbRoleMember.ps1 | `public/Remove-DbaDbRoleMember.ps1` | ソース | ロールメンバー削除（関連コマンド） |
