# 機能設計書 571-New-DbaServerRole

## 概要

本ドキュメントは、SQL Serverインスタンスにカスタムサーバーレベルロールを作成する `New-DbaServerRole` 機能の設計仕様を定義するものです。

### 本機能の処理概要

`New-DbaServerRole` は、SQL Serverインスタンス上に新しいサーバーレベルロールを作成するdbatools PowerShellコマンドレットです。このコマンドは、組み込みのサーバーロール（sysadmin、dbcreator等）では対応できないカスタムセキュリティ要件を満たすための、ユーザー定義サーバーロールを作成します。

**業務上の目的・背景**：組織においてSQL Serverのセキュリティ管理を効率化するため、サーバーレベルの権限をグループ化して管理する必要があります。例えば、バックアップオペレーター、監視担当者、特定のジョブ実行者など、組み込みロールでは対応しきれない中間的な権限セットを持つロールが必要な場合に、カスタムサーバーロールを作成します。

**機能の利用シーン**：
- 新規アプリケーション導入時の権限モデル構築
- セキュリティ監査後の権限整理・再構築
- 開発/テスト環境での権限テンプレート作成
- 複数インスタンスへの一括ロール展開

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. 既存ロールの重複チェック
3. SMO（SQL Server Management Objects）を使用した新規ServerRoleオブジェクトの作成
4. オーナーの設定（指定された場合）
5. Create()メソッドによるロールの永続化
6. 作成されたロールの情報を取得して出力

**関連システム・外部連携**：SQL Server SMOライブラリを使用してサーバーと通信します。Active Directory連携環境では、Windows認証を通じてドメインアカウントをロールオーナーとして設定可能です。

**権限による制御**：ロール作成には、対象インスタンスでのALTER ANY SERVER ROLE権限または同等の権限（sysadminメンバーシップ）が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | SSMSサーバーロール管理画面 | 参照画面 | GUIでのロール作成に相当する操作 |

## 機能種別

CRUD操作（Create）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | 有効なインスタンス名であること |
| SqlCredential | PSCredential | No | 代替認証情報 | 有効なPSCredentialオブジェクト |
| ServerRole | String[] | Yes | 作成するサーバーロール名 | 空でないこと |
| Owner | String | No | ロールのオーナーログイン | 存在するログインであること |
| EnableException | Switch | No | 例外を有効化するスイッチ | - |

### 入力データソース

- PowerShellコマンドライン入力
- パイプライン入力（SqlInstance）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverが動作するコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | 完全なインスタンス名（コンピュータ名\インスタンス名） |
| Role | String | サーバーロール名 |
| Login | Array | ロールのメンバーログイン一覧 |
| Owner | String | ロールのオーナー |
| IsFixedRole | Boolean | 固定ロールかどうか（新規作成は常にFalse） |
| DateCreated | DateTime | 作成日時 |
| DateModified | DateTime | 最終更新日時 |

### 出力先

- PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.ServerRoleオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ ServerRoleパラメータが指定されているか確認
2. インスタンスループ開始
   └─ 各SqlInstanceに対して処理を実行
3. インスタンス接続
   └─ Connect-DbaInstanceを使用して接続
4. 既存ロール確認
   └─ 同名ロールが存在しないかチェック
5. ロール作成処理
   └─ ShouldProcessによる確認後に実行
6. SMOオブジェクト作成
   └─ New-Objectでサーバーロールを生成
7. プロパティ設定
   └─ Name、Parent、Ownerを設定
8. Create()実行
   └─ データベースへのロール登録
9. 結果出力
   └─ Get-DbaServerRoleで作成されたロールを取得・出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{ServerRole指定あり?}
    B -->|No| C[エラー: ロール名必須]
    B -->|Yes| D[インスタンスループ開始]
    D --> E[Connect-DbaInstance]
    E --> F{接続成功?}
    F -->|No| G[エラー出力・次へ]
    F -->|Yes| H[ロールループ開始]
    H --> I{同名ロール存在?}
    I -->|Yes| J[警告出力・次へ]
    I -->|No| K{ShouldProcess確認}
    K -->|No| L[スキップ]
    K -->|Yes| M[ServerRoleオブジェクト作成]
    M --> N{Owner指定あり?}
    N -->|Yes| O[Owner設定]
    N -->|No| P[Create実行]
    O --> P
    P --> Q{作成成功?}
    Q -->|No| R[エラー出力]
    Q -->|Yes| S[Get-DbaServerRole]
    S --> T[結果出力]
    G --> U{次のインスタンス?}
    J --> V{次のロール?}
    L --> V
    R --> V
    T --> V
    V -->|Yes| H
    V -->|No| U
    U -->|Yes| D
    U -->|No| W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ロール名重複禁止 | 同一インスタンスに同名のサーバーロールは作成不可 | 常時 |
| BR-002 | オーナー存在確認 | Ownerに指定されたログインはインスタンスに存在する必要がある | Owner指定時 |
| BR-003 | 権限要件 | ALTER ANY SERVER ROLE権限が必要 | 常時 |

### 計算ロジック

特に計算ロジックはありません。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ロール作成 | sys.server_principals | INSERT | 新規サーバーロールの登録 |

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

#### sys.server_principals

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | パラメータServerRoleの値 | ロール名 |
| INSERT | type | 'R' | Server role |
| INSERT | owning_principal_id | Ownerのprincipal_id | 指定時のみ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | インスタンスへの接続失敗 | 接続情報・ネットワーク確認 |
| RoleExists | 重複エラー | 同名ロールが既に存在 | 別名を使用 |
| PermissionDenied | 権限エラー | ALTER ANY SERVER ROLE権限なし | 権限付与を依頼 |
| InvalidOwner | 無効オーナー | 指定されたオーナーが存在しない | 有効なログインを指定 |

### リトライ仕様

接続エラー時はStop-Functionで処理を中断し、次のインスタンスへ継続します。

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

SMOのCreate()メソッドによる暗黙的トランザクションで処理されます。失敗時は自動ロールバックされます。

## パフォーマンス要件

単一ロール作成は通常1秒以内で完了します。大量のインスタンスへの一括展開時は、並列処理を検討してください。

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

- 認証情報はPSCredentialオブジェクトで安全に受け渡し
- ALTER ANY SERVER ROLE権限の適切な管理が必要
- 監査ログによる操作追跡を推奨

## 備考

- SQL Server 2012以降でのみサーバーロールのカスタム作成が可能
- デフォルトオーナーは'dbo'（未指定時）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | ServerRole (SMO) | Microsoft.SqlServer.Management.Smo | SMOのServerRoleクラスの構造を理解 |

**読解のコツ**: SMOのServerRoleオブジェクトは、Name、Parent（Serverオブジェクト）、Ownerプロパティを持ちます。Create()メソッドでSQL Serverに永続化されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaServerRole.ps1 | `public/New-DbaServerRole.ps1` | 関数定義とパラメータバインディング |

**主要処理フロー**:
1. **81-88行目**: パラメータ定義（Mandatory、ValueFromPipeline等）
2. **89-93行目**: ServerRoleパラメータの必須チェック
3. **95-100行目**: インスタンス接続処理
4. **104-107行目**: 既存ロールの重複チェック
5. **109-126行目**: ロール作成のメイン処理

#### Step 3: 接続処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Connect-DbaInstance | `public/Connect-DbaInstance.ps1` | SQL Server接続の確立方法 |

**主要処理フロー**:
- **97行目**: Connect-DbaInstanceの呼び出し、$serverにSMO Serverオブジェクトが格納される

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaServerRole.ps1 | `public/New-DbaServerRole.ps1` | SMOを使用したロール作成 |

**主要処理フロー**:
- **112行目**: New-Object -TypeName Microsoft.SqlServer.Management.Smo.ServerRole でSMOオブジェクト作成
- **113-114行目**: Name、Parentプロパティの設定
- **116-118行目**: Owner指定時のオーナー設定
- **120行目**: Create()メソッドでロールを永続化
- **122行目**: Get-DbaServerRoleで作成結果を取得・出力

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

```
New-DbaServerRole
    │
    ├─ Connect-DbaInstance
    │      └─ SMO Server接続
    │
    ├─ Stop-Function (エラー時)
    │
    ├─ Write-Message (ログ出力)
    │
    ├─ New-Object Microsoft.SqlServer.Management.Smo.ServerRole
    │      └─ ServerRole.Create()
    │
    └─ Get-DbaServerRole
           └─ 作成されたロールの取得
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ────▶ SMO Server
                            │
ServerRole ─────────────────┼──────────────▶ ServerRole名チェック
                            │
                            ▼
                    SMO ServerRole作成
                            │
Owner ──────────────────────┼──────────────▶ Owner設定
                            │
                            ▼
                    ServerRole.Create()
                            │
                            ▼
                    Get-DbaServerRole ──────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaServerRole.ps1 | `public/New-DbaServerRole.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
| Get-DbaServerRole.ps1 | `public/Get-DbaServerRole.ps1` | ソース | ロール情報取得 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理 |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | メッセージ出力 |
