# 機能設計書 582-Repair-DbaDbOrphanUser

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Repair-DbaDbOrphanUser`コマンドレットに関する機能設計書です。本機能は孤立したデータベースユーザー（サーバーログインとの関連付けが切れたユーザー）を検出し、対応するサーバーログインに再マッピングするか、オプションで削除します。

### 本機能の処理概要

`Repair-DbaDbOrphanUser`は、データベース内で孤立状態になったユーザー（ログインプロパティが空のユーザー）を特定し、同名のサーバーログインに再マッピングして修復します。

**業務上の目的・背景**：データベースのリストア、マイグレーション、ログインの再作成後に、データベースユーザーがサーバーログインとの関連付けを失う「孤立ユーザー」問題が頻繁に発生します。この問題はアプリケーションの認証エラーや権限問題を引き起こすため、迅速な修復が必要です。本機能はこの一般的な問題を自動的に検出・修復します。

**機能の利用シーン**：
- データベースをバックアップから別サーバーにリストアした後
- サーバー間でデータベースをマイグレーションした後
- ログインを削除して再作成した後
- 災害復旧でデータベースを復元した後
- 定期的なセキュリティ監査でのチェックと修復

**主要な処理内容**：
1. 指定されたSQL Serverインスタンスへの接続
2. Get-DbaDbOrphanUserを使用した孤立ユーザーの検出
3. 同名のサーバーログイン（有効、非ロック、非システムオブジェクト）の存在確認
4. SQL Server 2005以上では`ALTER USER ... WITH LOGIN`、SQL Server 2000では`sp_change_users_login`を使用した再マッピング
5. RemoveNotExistingオプション指定時、対応ログインが存在しないユーザーの削除

**関連システム・外部連携**：Get-DbaDbOrphanUser、Remove-DbaDbOrphanUserコマンドレットを内部で使用します。

**権限による制御**：データベースへのアクセス権限とユーザー変更権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 38 | データベースユーザー管理 | 補助機能 | 孤立ユーザーの修復 |

## 機能種別

CRUD操作（Update/Delete） / データ修復

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象となるSQL Serverインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | SQL Server接続用の代替資格情報 | - |
| Database | object[] | No | スキャン対象のデータベース | ワイルドカード対応 |
| ExcludeDatabase | object[] | No | スキャンから除外するデータベース | - |
| Users | object[] | No | 修復対象の特定ユーザー | パイプライン入力対応 |
| RemoveNotExisting | switch | No | 対応ログインがないユーザーを削除 | - |
| Force | switch | No | 確認プロンプトをスキップ、スキーマ所有権をdboに変更 | - |
| EnableException | switch | No | 例外をスローするモードに切り替え | - |

### 入力データソース

- Get-DbaDbOrphanUserによる孤立ユーザー情報
- $server.Loginsによるサーバーログイン情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| DatabaseName | string | 孤立ユーザーが存在するデータベース名 |
| User | string | 孤立データベースユーザー名 |
| Status | string | 修復結果（Success, No matching login） |

### 出力先

PowerShellパイプラインへのPSCustomObjectの出力

## 処理フロー

### 処理シーケンス

```
1. パラメータ処理
   └─ Force指定時、ConfirmPreference = 'none'に設定

2. SQL Serverインスタンスへの接続
   └─ Connect-DbaInstanceを使用して接続を確立

3. データベースの取得とフィルタリング
   └─ IsAccessible=trueのデータベースを取得
   └─ Database/ExcludeDatabaseパラメータでフィルタリング

4. 孤立ユーザーの検出
   └─ Get-DbaDbOrphanUserで各データベースの孤立ユーザーを取得
   └─ Usersパラメータ指定時は対象ユーザーをフィルタリング

5. 各孤立ユーザーの処理
   └─ 同名の有効なサーバーログイン存在確認
   └─ ログイン存在時：ALTER USER / sp_change_users_loginで再マッピング
   └─ ログイン不在時：RemoveNotExisting指定ならRemove-DbaDbOrphanUser呼び出し

6. 結果の出力
   └─ PSCustomObjectとして操作結果を出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[エラー出力]
    C -->|Yes| E[データベース取得・フィルタリング]
    E --> F{データベース存在?}
    F -->|No| G[処理なしで終了]
    F -->|Yes| H[Get-DbaDbOrphanUser]
    H --> I{孤立ユーザー存在?}
    I -->|No| J[次のDB]
    I -->|Yes| K[各ユーザーをループ]
    K --> L{対応ログイン存在?}
    L -->|Yes| M[ALTER USER実行]
    M --> N[Success出力]
    L -->|No| O{RemoveNotExisting?}
    O -->|Yes| P[ユーザー追加リストへ]
    O -->|No| Q[No matching login出力]
    N --> R{次のユーザー?}
    Q --> R
    P --> R
    R -->|Yes| K
    R -->|No| S{RemoveNotExisting?}
    S -->|Yes| T[Remove-DbaDbOrphanUser呼び出し]
    S -->|No| J
    T --> J
    J --> U{次のDB?}
    U -->|Yes| H
    U -->|No| V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-582-01 | ログイン適格条件 | 再マッピング対象のログインは有効、非システム、非ロックであること | 常時 |
| BR-582-02 | バージョン別SQL | SQL Server 2005+はALTER USER、2000はsp_change_users_login | バージョンに応じて |
| BR-582-03 | Forceとスキーマ | Force指定時はスキーマ所有権をdboに変更してユーザー削除可能 | RemoveNotExisting+Force時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ユーザー再マッピング | sys.database_principals | UPDATE | ユーザーとログインの関連付けを更新 |
| ユーザー削除 | sys.database_principals | DELETE | RemoveNotExisting時にユーザーを削除 |

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

#### sys.database_principals

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | sid | ログインのSIDに更新 | ALTER USERで内部的に更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | Stop-Functionでエラー出力 |
| - | DatabaseError | データベースアクセス失敗 | Stop-Functionで継続処理 |

### リトライ仕様

リトライ処理なし。各データベースは独立して処理され、エラー発生時は次のデータベースに進みます。

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

各ユーザーの修復は個別のSQL文として実行されます。明示的なトランザクション管理はありません。

## パフォーマンス要件

特に規定なし。大量のデータベースや孤立ユーザーがある場合は処理時間が増加します。

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

- データベースユーザー変更権限が必要
- SupportsShouldProcess実装（ConfirmImpact = "Medium"）
- Force指定時のスキーマ所有権変更には注意が必要

## 備考

- 内部でGet-DbaDbOrphanUser、Remove-DbaDbOrphanUserを呼び出し
- SQL Server 2000/2005+両方に対応したデュアル実装

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造と、孤立ユーザーの判定基準を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 182-189行目: 成功時の出力構造 |
| 1-2 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 197-204行目: 失敗時の出力構造 |

**読解のコツ**: PSCustomObjectはComputerName、InstanceName、SqlInstance、DatabaseName、User、Statusの6プロパティを持ちます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 115-127行目: パラメータ定義 |
| 2-2 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 128-130行目: beginブロック（Force処理） |

**主要処理フロー**:
1. **115-127行目**: パラメータ定義（SqlInstanceが必須、パイプライン入力対応）
2. **129行目**: Force時にConfirmPreferenceを'none'に設定

#### Step 3: データベースフィルタリング

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 140-147行目: データベースのフィルタリング |

**主要処理フロー**:
- **140行目**: `IsAccessible`でアクセス可能なDBを取得
- **142-144行目**: Databaseパラメータでフィルタ
- **145-147行目**: ExcludeDatabaseパラメータで除外

#### Step 4: 孤立ユーザー検出と修復

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 155-158行目: Get-DbaDbOrphanUser呼び出し |
| 4-2 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 164-169行目: ログイン適格性チェック |
| 4-3 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 171-179行目: バージョン別SQL実行 |

**主要処理フロー**:
- **155行目**: `Get-DbaDbOrphanUser`で孤立ユーザー取得
- **164-169行目**: ログインの有効性確認（Isdisabled=False、IsSystemObject=False、IsLocked=False）
- **172行目**: SQL Server 2005+用`ALTER USER`
- **175行目**: SQL Server 2000用`sp_change_users_login`

#### Step 5: 削除処理（RemoveNotExisting）

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | 210-221行目: Remove-DbaDbOrphanUser呼び出し |

**主要処理フロー**:
- **192-194行目**: 対応ログインがないユーザーをコレクションに追加
- **210-221行目**: RemoveNotExisting時にRemove-DbaDbOrphanUserを呼び出し
- **211行目**: Force時は-Forceパラメータを追加

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

```
Repair-DbaDbOrphanUser
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Get-DbaDbOrphanUser
    │      └─ 孤立ユーザーの検出
    │
    ├─ $server.Logins (フィルタリング)
    │      └─ 有効・非ロック・非システムログインの検索
    │
    ├─ ExecuteNonQuery
    │      ├─ ALTER USER (SQL 2005+)
    │      └─ sp_change_users_login (SQL 2000)
    │
    └─ Remove-DbaDbOrphanUser [RemoveNotExisting時]
           └─ 対応ログインがないユーザーの削除
```

### データフロー図

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

SqlInstance ───────────▶ Connect-DbaInstance ──────────▶ $server
                              │
Database/Exclude ──────▶ データベースフィルタ ─────────▶ $DatabaseCollection
                              │
                         Get-DbaDbOrphanUser ──────────▶ $UsersToWork
                              │
Users ─────────────────▶ ユーザーフィルタ ─────────────▶ 対象ユーザー
                              │
                         ログイン照合 ─────────────────▶ 再マッピング or 削除リスト
                              │
                         ALTER USER / Remove ──────────▶ PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Repair-DbaDbOrphanUser.ps1 | `public/Repair-DbaDbOrphanUser.ps1` | ソース | メイン処理 |
| Get-DbaDbOrphanUser.ps1 | `public/Get-DbaDbOrphanUser.ps1` | ソース | 孤立ユーザー検出 |
| Remove-DbaDbOrphanUser.ps1 | `public/Remove-DbaDbOrphanUser.ps1` | ソース | ユーザー削除 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
