# 帳票設計書 12-Export-DbaUser

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Export-DbaUser` コマンドに関する帳票設計書です。このコマンドは、データベースユーザーをロール・権限付きでT-SQLスクリプトとして生成する機能を提供します。

### 本帳票の処理概要

Export-DbaUserは、SQL Serverデータベース内のユーザー定義を、完全なセキュリティコンテキスト（ロールメンバーシップ、データベースレベル権限、オブジェクトレベル権限）と共にT-SQLスクリプトとして出力するコマンドです。

**業務上の目的・背景**：データベースセキュリティは企業システムの重要な構成要素です。環境間でのユーザー移行、コンプライアンス監査用のセキュリティドキュメント化、災害復旧時のセキュリティ設定再構築において、ユーザー定義と権限の正確な再現が必要です。本コマンドは、手動設定によるミスを防ぎ、セキュリティ移行の効率化と監査対応を支援します。

**帳票の利用シーン**：
- 開発・テスト・本番環境間でのユーザーセキュリティ設定の移行
- コンプライアンス監査用のデータベースセキュリティドキュメント作成
- 災害復旧手順書の一部としてのセキュリティ構成バックアップ
- アプリケーションデプロイメントスクリプトの作成
- テンプレート化による再利用可能なセキュリティスクリプト生成

**主要な出力内容**：
1. CREATE USER文（ユーザー作成）
2. CREATE ROLE文（カスタムロール作成）
3. sp_addrolemember / ALTER ROLE ADD MEMBER文（ロールメンバーシップ）
4. GRANT/DENY/REVOKE文（データベースレベル権限）
5. オブジェクトレベル権限（テーブル、ビュー、ストアドプロシージャ等）

**帳票の出力タイミング**：PowerShellコンソールまたはスクリプトからコマンド実行時に即座に出力されます。

**帳票の利用者**：データベース管理者（DBA）、セキュリティ管理者、アプリケーション開発者、IT監査担当者

## 帳票種別

スクリプトファイル（T-SQL形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | コマンドライン | Export-DbaUser コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | SQL（T-SQLスクリプト） |
| 用紙サイズ | N/A（テキストファイル） |
| 向き | N/A |
| ファイル名 | {ServerName}-{UserName}-{timestamp}.sql（自動生成時） |
| 出力方法 | ファイル保存 / コンソール出力（Passthru） |
| 文字コード | UTF-8（デフォルト、変更可能） |

### SQL固有設定

| 項目 | 内容 |
|-----|------|
| バッチ区切り | GO（ExcludeGoBatchSeparatorで除外可能） |
| USE文 | データベースコンテキスト含む |
| IF NOT EXISTS | ScriptingOptionsで制御可能 |

## 帳票レイアウト

### レイアウト概要

T-SQLスクリプトとして出力されるため、スクリプト構造として定義されます。

```
┌─────────────────────────────────────┐
│      USE [DatabaseName]             │
│             GO                      │
├─────────────────────────────────────┤
│      ロール定義部                    │
│   (CREATE ROLE ステートメント)       │
├─────────────────────────────────────┤
│      ユーザー作成部                  │
│   (CREATE USER ステートメント)       │
│   (sp_addrolemember等)              │
├─────────────────────────────────────┤
│      データベース権限部              │
│   (GRANT/DENY/REVOKE)               │
├─────────────────────────────────────┤
│      オブジェクト権限部              │
│   (GRANT ON OBJECT:: 等)            │
└─────────────────────────────────────┘
```

### ヘッダー部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | USE文 | データベースコンテキスト | Database.Name | USE [dbname] |

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 列幅 |
|----|-------|------|-------------|---------|-----|
| 1 | ロール定義 | カスタムロール作成文 | Database.Roles | CREATE ROLE | 可変 |
| 2 | ユーザー定義 | ユーザー作成文 | User.Script() | CREATE USER | 可変 |
| 3 | ロールメンバーシップ | ロール所属設定 | User.Script() | sp_addrolemember | 可変 |
| 4 | DB権限 | データベース権限 | EnumDatabasePermissions | GRANT/DENY/REVOKE | 可変 |
| 5 | オブジェクト権限 | オブジェクトレベル権限 | EnumObjectPermissions | GRANT ON OBJECT | 可変 |

### フッター部

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | GO | バッチ区切り | 固定 | GO |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| SqlInstance | 対象SQL Serverインスタンス | Yes（InputObjectがない場合） |
| Database | 対象データベース | No（全DB対象） |
| User | 特定ユーザー名 | No（全ユーザー対象） |
| ExcludeDatabase | 除外データベース | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | データベース順 | InputObject順 |
| 2 | ユーザー順 | コレクション順 |

### 改ページ条件

N/A（テキストファイル出力のため）

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| sys.database_principals | ユーザー・ロール一覧 | SMO経由 |
| sys.database_permissions | データベース権限 | EnumDatabasePermissions |
| sys.database_role_members | ロールメンバーシップ | SMO経由 |
| 各オブジェクトカタログ | オブジェクト権限 | EnumObjectPermissions |

### テーブル別参照項目詳細

#### SMO Database.Users コレクション

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| Name | ユーザー名 | IsSystemObject = false | ##ユーザー除外 |
| Login | 関連ログイン名 | - | Template使用時に置換 |

#### EnumDatabasePermissions / EnumObjectPermissions

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| PermissionType | 権限種別 | - | SELECT, EXECUTE等 |
| PermissionState | 権限状態 | - | Grant/Deny/Revoke |
| ObjectName | 対象オブジェクト | - | テーブル、ビュー等 |
| Grantee | 権限付与先 | - | ユーザー名 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| N/A | 計算処理なし | - | 権限列挙のみ |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaUser実行] --> B[Get-DbaDatabase]
    B --> C[Database取得]
    C --> D{User指定?}
    D -->|Yes| E[指定ユーザーフィルタ]
    D -->|No| F[全ユーザー対象]
    E --> G[ループ: 各ユーザー]
    F --> G
    G --> H[ロール定義スクリプト生成]
    H --> I[ユーザースクリプト生成]
    I --> J[DB権限スクリプト生成]
    J --> K[オブジェクト権限スクリプト生成]
    K --> L{Template?}
    L -->|Yes| M[プレースホルダー置換]
    L -->|No| N[スクリプト結合]
    M --> N
    N --> O{Passthru?}
    O -->|Yes| P[コンソール出力]
    O -->|No| Q[ファイル保存]
    P --> R[次ユーザー or 終了]
    Q --> R
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| バージョン非互換 | 互換性レベルが宛先より低い | "This user may be using functionality from {version}..." | 宛先バージョンを確認 |
| 接続エラー | データベース取得失敗 | Stop-Function | 接続情報を確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1〜1000ユーザー |
| 目標出力時間 | ユーザー数に依存（1ユーザー/秒程度） |
| 同時出力数上限 | 制限なし |

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

- パスワードは出力されない（ユーザー定義のみ）
- Templateモードで{templateUser}/{templateLogin}プレースホルダー使用可能
- 出力されるスクリプトには機密性のある権限情報が含まれる
- SQL Server 2000以上をサポート

## 備考

- GenerateFilePerUserオプションでユーザー毎のファイル分割が可能
- ScriptingOptionsObjectで詳細なスクリプト生成オプション指定可能
- DestinationVersionでターゲットバージョン互換スクリプト生成
- ExcludeGoBatchSeparatorでGO区切りなしスクリプト生成

---

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

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

### 推奨読解順序

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

権限列挙とスクリプト生成の仕組みを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaUser.ps1 | `public/Export-DbaUser.ps1` | パラメータ定義（行163-187）でScriptingOptionsObject等を確認 |
| 1-2 | Export-DbaUser.ps1 | `public/Export-DbaUser.ps1` | バージョンマッピング（行195-217）で互換性制御を理解 |

**読解のコツ**: SMOのScriptingOptionsとSQLバージョン互換性の関係を理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaUser.ps1 | `public/Export-DbaUser.ps1` | processブロック（行222-609）がメイン処理 |

**主要処理フロー**:
1. **行225-227**: SqlInstanceからデータベース取得
2. **行232-259**: ユーザーフィルタリング
3. **行355-363**: ロールスクリプト生成
4. **行366-385**: ユーザースクリプト生成（Template置換含む）
5. **行388-403**: データベース権限スクリプト生成
6. **行413-563**: オブジェクト権限スクリプト生成

#### Step 3: 権限列挙処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaUser.ps1 | `public/Export-DbaUser.ps1` | オブジェクト権限収集（行413-477） |

**主要処理フロー**:
- **行413-415**: perms ArrayList初期化、EnumObjectPermissions
- **行417-477**: 各オブジェクトタイプからの権限収集
- **行479-563**: 権限種別ごとのスクリプト生成

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaUser.ps1 | `public/Export-DbaUser.ps1` | 出力分岐（行583-608） |

**主要処理フロー**:
- **行569-580**: GO区切り処理
- **行583-602**: ファイル出力 or Passthru処理
- **行606-608**: 単一ファイル出力時のFileInfo返却

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

```
Export-DbaUser
    │
    ├─ Test-ExportDirectory (begin)
    │      └─ パス存在確認
    │
    ├─ Get-DbaDatabase
    │      └─ データベースオブジェクト取得
    │
    ├─ New-DbaScriptingOption
    │      └─ スクリプトオプション生成
    │
    ├─ Database.Roles.EnumMembers()
    │      └─ ロールメンバーシップ確認
    │
    ├─ Role.Script()
    │      └─ ロールスクリプト生成
    │
    ├─ User.Script()
    │      └─ ユーザースクリプト生成
    │
    ├─ Database.EnumDatabasePermissions()
    │      └─ DB権限列挙
    │
    ├─ Object.EnumObjectPermissions()
    │      └─ オブジェクト権限列挙
    │
    ├─ Get-ExportFilePath
    │      └─ 出力ファイルパス決定
    │
    └─ Out-File
           └─ ファイル出力
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaDatabase ───────────▶ Database Objects
                            │
Database ──────────▶ Filter Databases ───────────▶ Target Databases
                            │
                            ▼
User ──────────────▶ Filter Users ───────────────▶ Target Users
                            │
                            ▼
                     Role.Script() ──────────────▶ Role T-SQL
                            │
                     User.Script() ──────────────▶ User T-SQL
                            │
                     EnumDatabasePermissions() ──▶ DB Permission T-SQL
                            │
                     EnumObjectPermissions() ────▶ Object Permission T-SQL
                            │
                            ▼
Template ──────────▶ Placeholder Replace ────────▶ Templated Script
                            │
                            ▼
Path/FilePath ─────▶ Out-File ───────────────────▶ .sql File(s)
    or
Passthru ──────────▶ Console Output ─────────────▶ String Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaUser.ps1 | `public/Export-DbaUser.ps1` | ソース | メイン処理 |
| Export-DbaUser.Tests.ps1 | `tests/Export-DbaUser.Tests.ps1` | テスト | 単体テスト |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | DB取得 |
| New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | ソース | スクリプトオプション |
| Get-ExportFilePath.ps1 | `private/Get-ExportFilePath.ps1` | ソース | 出力パス決定 |
| Test-ExportDirectory.ps1 | `private/Test-ExportDirectory.ps1` | ソース | ディレクトリ検証 |
