# 画面設計書 115-マイグレーション

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverインスタンス全体のマイグレーション機能の設計仕様を記述する。

### 本画面の処理概要

本機能は、SQL Serverインスタンス全体を移行元から移行先へ包括的に移行する「イージーボタン」機能である。データベース、ログイン、サーバー構成、SQL Agentジョブ、リンクサーバー、エンドポイント、その他のサーバーオブジェクトを一括で移行する。

**業務上の目的・背景**：新しいハードウェアへのサーバー移行、バージョンアップグレード、サーバー統合などの大規模移行作業を効率化する。個別の移行コマンドを使用するよりも柔軟性は低いが、完全なインスタンス移行ワークフローの複雑さを自動化で解消する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドレットを実行する。
- `Start-DbaMigration` - インスタンス全体の移行実行

**主要な操作・処理内容**：
1. データベースの移行（Backup/RestoreまたはDetach/Attach方式）
2. ログインとパスワード/SIDの移行
3. SQL Server構成（sp_configure）の移行
4. SQL Agentジョブ/スケジュール/オペレーターの移行
5. リンクサーバー/資格情報の移行
6. データベースメール/Central Management Serverの移行
7. Resource Governor/監査/エンドポイントの移行

**画面遷移**：本機能はコマンドラインインターフェースであり、画面遷移は存在しない。内部で複数のCopy-Dba*コマンドレットを順次呼び出す。

**権限による表示制御**：移行元・移行先の両方でsysadmin権限が必要。データベースファイルへのアクセスには適切なファイルシステム権限も必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 260 | Start-DbaMigration | 主機能 | インスタンス全体の移行 |

## 画面種別

CLIコマンド（マイグレーション）

## URL/ルーティング

```powershell
# Backup/Restore方式
Start-DbaMigration -Source <移行元> -Destination <移行先> -BackupRestore -SharedPath <バックアップパス>

# Detach/Attach方式
Start-DbaMigration -Source <移行元> -Destination <移行先> -DetachAttach [-Reattach]

# 特定オブジェクトを除外
Start-DbaMigration -Source <移行元> -Destination <移行先> -BackupRestore -SharedPath <パス> -Exclude Databases,Logins
```

## 入出力項目

### Start-DbaMigration パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|---|------|-------------|------|
| Source | DbaInstanceParameter | No | - | 移行元SQL Serverインスタンス |
| Destination | DbaInstanceParameter[] | No | - | 移行先SQL Serverインスタンス（複数可） |
| SourceSqlCredential | PSCredential | No | - | 移行元認証資格情報 |
| DestinationSqlCredential | PSCredential | No | - | 移行先認証資格情報 |
| BackupRestore | switch | No | $false | Backup/Restore方式を使用 |
| SharedPath | string | No | - | バックアップファイルの共有パス（UNC/Azure URL） |
| DetachAttach | switch | No | $false | Detach/Attach方式を使用 |
| Reattach | switch | No | $false | 移行後に移行元でデータベースを再アタッチ |
| WithReplace | switch | No | $false | 既存データベースを強制上書き |
| NoRecovery | switch | No | $false | NORECOVERY状態でリストア |
| ReuseSourceFolderStructure | switch | No | $false | 移行元のフォルダ構造を維持 |
| SetSourceReadOnly | switch | No | $false | 移行前に移行元DBを読み取り専用に設定 |
| SetSourceOffline | switch | No | $false | 移行前に移行元DBをオフラインに設定 |
| IncludeSupportDbs | switch | No | $false | ReportServer/SSISDB等を含める |
| UseLastBackup | switch | No | $false | 既存の最新バックアップを使用 |
| Continue | switch | No | $false | 既存のRESTORING状態DBにログを適用 |
| KeepCDC | switch | No | $false | CDC設定を維持 |
| KeepReplication | switch | No | $false | レプリケーション設定を維持 |
| Exclude | string[] | No | - | 移行から除外するコンポーネント |
| ExcludeSaRename | switch | No | $false | saアカウント名の同期をスキップ |
| DisableJobsOnDestination | switch | No | $false | 移行先でジョブを無効化 |
| DisableJobsOnSource | switch | No | $false | 移行元でジョブを無効化 |
| AzureCredential | string | No | - | Azure Storage用資格情報名 |
| MasterKeyPassword | SecureString | No | - | マスターキーのパスワード |
| Force | switch | No | $false | 確認なしで上書き |
| WhatIf | switch | No | - | 実行内容をシミュレート |
| Confirm | switch | No | - | 確認プロンプトを表示 |
| EnableException | switch | No | $false | 例外をスローする |

### Excludeパラメータの有効値

| 値 | 説明 |
|-----|------|
| Databases | データベースの移行を除外 |
| Logins | ログインの移行を除外 |
| AgentServer | SQL Agentオブジェクトを除外 |
| Credentials | 資格情報を除外 |
| LinkedServers | リンクサーバーを除外 |
| SpConfigure | sp_configure設定を除外 |
| CentralManagementServer | CMSを除外 |
| DatabaseMail | データベースメールを除外 |
| SysDbUserObjects | システムDB内ユーザーオブジェクトを除外 |
| SystemTriggers | システムトリガーを除外 |
| BackupDevices | バックアップデバイスを除外 |
| Audits | 監査を除外 |
| Endpoints | エンドポイントを除外 |
| ExtendedEvents | 拡張イベントを除外 |
| PolicyManagement | ポリシー管理を除外 |
| ResourceGovernor | Resource Governorを除外 |
| ServerAuditSpecifications | サーバー監査仕様を除外 |
| CustomErrors | カスタムエラーを除外 |
| ServerRoles | サーバーロールを除外 |
| DataCollector | Data Collectorを除外 |
| StartupProcedures | スタートアッププロシージャを除外 |
| ExtendedStoredProcedures | 拡張ストアドプロシージャを除外 |
| AgentServerProperties | SQL Agentプロパティを除外 |
| MasterCertificates | マスター証明書を除外 |

## 表示項目

### Start-DbaMigration 出力（Copy-DbaDatabase出力）

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| (Copy-DbaDatabase出力) | object | データベース移行結果 |

出力はCopy-DbaDatabase（-Exclude Databasesでない場合）の結果。その他の移行操作は-Verboseで進捗確認。

## イベント仕様

### 1-移行開始

1. パラメータ検証（BackupRestoreまたはDetachAttach必須）
2. Connect-DbaInstanceで移行元に接続
3. Stopwatchで所要時間計測開始

### 2-各コンポーネント移行

以下の順序で各コンポーネントを移行（Exclude指定がない場合）:

1. **SpConfigure**: Copy-DbaSpConfigure
2. **MasterCertificates**: Copy-DbaDbCertificate (master)
3. **CustomErrors**: Copy-DbaCustomError
4. **ServerRoles**: Copy-DbaServerRole
5. **Credentials**: Copy-DbaCredential
6. **DatabaseMail**: Copy-DbaDbMail
7. **CentralManagementServer**: Copy-DbaRegServer
8. **BackupDevices**: Copy-DbaBackupDevice
9. **SystemTriggers**: Copy-DbaInstanceTrigger
10. **Databases**: Copy-DbaDatabase（メイン出力）
11. **Logins**: Copy-DbaLogin + Update-SqlDbOwner
12. **LinkedServers**: Copy-DbaLinkedServer
13. **DataCollector**: Copy-DbaDataCollector
14. **Audits**: Copy-DbaInstanceAudit
15. **ServerAuditSpecifications**: Copy-DbaInstanceAuditSpecification
16. **Endpoints**: Copy-DbaEndpoint
17. **PolicyManagement**: Copy-DbaPolicyManagement
18. **ResourceGovernor**: Copy-DbaResourceGovernor
19. **SysDbUserObjects**: Copy-DbaSystemDbUserObject
20. **ExtendedEvents**: Copy-DbaXESession
21. **AgentServer**: Copy-DbaAgentServer
22. **StartupProcedures**: Copy-DbaStartupProcedure
23. **ExtendedStoredProcedures**: Copy-DbaExtendedStoredProcedure

### 3-移行完了

1. 総所要時間を計算
2. VerboseメッセージでサマリーOutput

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

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

| 操作（イベント） | 対象オブジェクト | 操作種別 | 概要 |
|----------------|-----------------|---------|------|
| Copy Databases | sys.databases | INSERT | データベース移行 |
| Copy Logins | sys.server_principals | INSERT | ログイン移行 |
| Copy SpConfigure | sys.configurations | UPDATE | 構成変更 |
| Copy AgentServer | msdb | INSERT | エージェントオブジェクト |

## メッセージ仕様

| メッセージ種別 | メッセージ内容 | 発生条件 |
|---------------|---------------|---------|
| エラー | You must specify a database migration method (-BackupRestore or -DetachAttach) or -Exclude Databases | 移行方式未指定 |
| エラー | -DetachAttach cannot be used with -BackupRestore or -UseLastBackup | 排他的パラメータ |
| エラー | When using -BackupRestore, you must specify -SharedPath or -UseLastBackup | SharedPath未指定 |
| エラー | -SharedPath cannot be used with -UseLastBackup | 排他的パラメータ |
| エラー | URL shared storage is only supported by BackupRestore | Azure URLでDetachAttach |
| エラー | When using -DetachAttach with multiple servers, you must specify -Reattach | 複数移行先でReattachなし |
| エラー | -Continue cannot be used without -UseLastBackup | Continue単独使用 |
| 警告 | Collation on $Source differs from the $Destination | 照合順序の不一致 |
| Verbose | SQL Server migration complete | 移行完了 |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| パラメータ不正 | Stop-Functionでエラー出力、return |
| 接続失敗 | Stop-Functionでエラー出力、return |
| 各Copy-*失敗 | 個別コマンドのエラー処理に依存 |

## 備考

- BackupRestore方式は本番環境向け（DBをデタッチしない）
- DetachAttach方式は高速だがダウンタイムが発生
- DetachAttachはミラーリング/AGを破壊する可能性あり
- Forceで既存オブジェクトを削除して再作成
- IncludeSupportDbsでReportServer/SSISDB/distributionを含める
- UseLastBackupは新規バックアップを作成せず既存バックアップを使用
- NoRecoveryでRESTORING状態のまま残し追加ログ適用可能
- ExcludeSaRenameでsa名の同期をスキップ

---

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

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

### 推奨読解順序

#### Step 1: パラメータとバリデーションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行242-271: パラメータ定義 |
| 1-2 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行273-309: beginブロックでのバリデーション |

**読解のコツ**: BackupRestoreとDetachAttachは排他的。SharedPathまたはUseLastBackupが必要。

#### Step 2: 移行フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行357-361: SpConfigure移行 |
| 2-2 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行412-457: Database移行 |
| 2-3 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行459-464: Login移行 |

**主要処理フロー**:
1. **行350-355**: Connect-DbaInstanceで接続
2. **行357-547**: 各コンポーネントを順次移行
3. **行549-555**: 完了メッセージと所要時間

#### Step 3: データベース移行の詳細

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行416-427: CopyDatabaseSplatベース |
| 3-2 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行428-452: BackupRestore/DetachAttach分岐 |
| 3-3 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | 行454-456: Copy-DbaDatabase実行 |

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

```
Start-DbaMigration
    │
    +-- パラメータバリデーション
    │       └─ BackupRestore/DetachAttach確認
    │
    +-- Connect-DbaInstance
    │       └─ 移行元接続
    │
    +-- Copy-DbaSpConfigure (SpConfigure)
    │
    +-- Copy-DbaDbCertificate (MasterCertificates)
    │       └─ master DB証明書
    │
    +-- Copy-DbaCustomError (CustomErrors)
    │
    +-- Copy-DbaServerRole (ServerRoles)
    │
    +-- Copy-DbaCredential (Credentials)
    │
    +-- Copy-DbaDbMail (DatabaseMail)
    │
    +-- Copy-DbaRegServer (CentralManagementServer)
    │
    +-- Copy-DbaBackupDevice (BackupDevices)
    │
    +-- Copy-DbaInstanceTrigger (SystemTriggers)
    │
    +-- Copy-DbaDatabase (Databases) ─────────> 出力
    │       ├─ BackupRestore方式
    │       │   └─ SharedPath/UseLastBackup
    │       └─ DetachAttach方式
    │           └─ Reattach
    │
    +-- Copy-DbaLogin (Logins)
    │       └─ Update-SqlDbOwner (DBオーナー同期)
    │
    +-- Copy-DbaLinkedServer (LinkedServers)
    │
    +-- Copy-DbaDataCollector (DataCollector)
    │
    +-- Copy-DbaInstanceAudit (Audits)
    │
    +-- Copy-DbaInstanceAuditSpecification (ServerAuditSpecifications)
    │
    +-- Copy-DbaEndpoint (Endpoints)
    │
    +-- Copy-DbaPolicyManagement (PolicyManagement)
    │
    +-- Copy-DbaResourceGovernor (ResourceGovernor)
    │
    +-- Copy-DbaSystemDbUserObject (SysDbUserObjects)
    │
    +-- Copy-DbaXESession (ExtendedEvents)
    │
    +-- Copy-DbaAgentServer (AgentServer)
    │
    +-- Copy-DbaStartupProcedure (StartupProcedures)
    │
    └── Copy-DbaExtendedStoredProcedure (ExtendedStoredProcedures)
```

### データフロー図

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

Source ──────────────────> Connect-DbaInstance ─────────────────>
Destination ─────────────>

BackupRestore ───────────> Copy-DbaDatabase ───────────────────>
SharedPath ──────────────>     │
UseLastBackup ───────────>     ├─ Backup/Restore方式             Database Migration
                               │   └─ 共有パスにバックアップ       Status Object
DetachAttach ────────────>     └─ Detach/Attach方式
Reattach ────────────────>         └─ BITS経由でファイルコピー

Exclude以外の              各Copy-Dba*コマンド ─────────────────> (Verbose Output)
コンポーネント ──────────>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | ソース | インスタンス全体移行 |
| Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | ソース | データベース移行（依存） |
| Copy-DbaLogin.ps1 | `public/Copy-DbaLogin.ps1` | ソース | ログイン移行（依存） |
| Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | ソース | SQL Agent移行（依存） |
| Copy-DbaSpConfigure.ps1 | `public/Copy-DbaSpConfigure.ps1` | ソース | sp_configure移行（依存） |
| Copy-DbaLinkedServer.ps1 | `public/Copy-DbaLinkedServer.ps1` | ソース | リンクサーバー移行（依存） |
| Copy-DbaResourceGovernor.ps1 | `public/Copy-DbaResourceGovernor.ps1` | ソース | Resource Governor移行（依存） |
| Copy-DbaEndpoint.ps1 | `public/Copy-DbaEndpoint.ps1` | ソース | エンドポイント移行（依存） |
