# 機能設計書 362-Start-DbaMigration

## 概要

本ドキュメントは、SQL Serverインスタンス全体を移行するための dbatools コマンド `Start-DbaMigration` の機能設計を記述する。

### 本機能の処理概要

`Start-DbaMigration` は、ソースSQL Serverインスタンスからターゲットインスタンスへ、データベース、ログイン、サーバー構成、各種サーバーオブジェクトを一括で移行する「イージーボタン」として機能する包括的な移行コマンドである。

**業務上の目的・背景**：SQL Serverインスタンスの移行は、ハードウェア更新、バージョンアップグレード、サーバー統合など様々な場面で必要となる。個別の移行コマンドを順番に実行することは複雑で時間がかかり、漏れが発生しやすい。本コマンドは、dbatoolsの多数の移行ツールを統合し、完全なインスタンス移行ワークフローを1つのコマンドで実現する。

**機能の利用シーン**：
- SQL Serverを新しいハードウェアに移行する際
- SQL Serverのバージョンアップグレード時
- 複数のSQL Serverインスタンスを1つに統合する際
- ディザスタリカバリ環境の構築・更新時

**主要な処理内容**：
1. sp_configure設定の移行（Copy-DbaSpConfigure）
2. masterデータベース内の証明書の移行（Copy-DbaDbCertificate）
3. カスタムエラーメッセージの移行（Copy-DbaCustomError）
4. サーバーロールの移行（Copy-DbaServerRole）
5. 資格情報の移行（Copy-DbaCredential）
6. データベースメールの移行（Copy-DbaDbMail）
7. Central Management Serverの移行（Copy-DbaRegServer）
8. バックアップデバイスの移行（Copy-DbaBackupDevice）
9. システムトリガーの移行（Copy-DbaInstanceTrigger）
10. データベースの移行（Copy-DbaDatabase - BackupRestore/DetachAttach）
11. ログインの移行（Copy-DbaLogin）
12. データベースオーナーの更新（Update-SqlDbOwner）
13. リンクサーバーの移行（Copy-DbaLinkedServer）
14. Data Collectorの移行（Copy-DbaDataCollector）
15. 監査の移行（Copy-DbaInstanceAudit）
16. サーバー監査仕様の移行（Copy-DbaInstanceAuditSpecification）
17. エンドポイントの移行（Copy-DbaEndpoint）
18. Policy Managementの移行（Copy-DbaPolicyManagement）
19. Resource Governorの移行（Copy-DbaResourceGovernor）
20. システムデータベースユーザーオブジェクトの移行（Copy-DbaSystemDbUserObject）
21. Extended Eventsの移行（Copy-DbaXESession）
22. SQL Server Agentの移行（Copy-DbaAgentServer）
23. スタートアッププロシージャの移行（Copy-DbaStartupProcedure）
24. Extended Stored Proceduresの移行（Copy-DbaExtendedStoredProcedure）

**関連システム・外部連携**：各サブコマンドを順次呼び出し、SMO/WMI/T-SQLを介してSQL Serverと連携

**権限による制御**：各移行対象に応じた権限が必要（通常sysadmin推奨）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIツール | 主機能 | PowerShellコンソールから実行 |

## 機能種別

データ連携 / 統合移行処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | No | ソースSQL Serverインスタンス | - |
| Destination | DbaInstanceParameter[] | No | ターゲットSQL Serverインスタンス（複数可） | - |
| SourceSqlCredential | PSCredential | No | ソースへの接続資格情報 | - |
| DestinationSqlCredential | PSCredential | No | ターゲットへの接続資格情報 | - |
| BackupRestore | switch | No | バックアップ/リストア方式でDB移行 | UseLastBackupと排他 |
| SharedPath | string | No | バックアップファイルの共有パス（UNC/Azure URL） | BackupRestore時に必要 |
| DetachAttach | switch | No | デタッチ/アタッチ方式でDB移行 | BackupRestoreと排他 |
| Reattach | switch | No | ソースDBを再アタッチ | DetachAttach時に使用 |
| NoRecovery | switch | No | NORECOVERY状態でリストア | BackupRestore時のみ |
| WithReplace | switch | No | 既存DBを上書き | BackupRestore時のみ |
| ReuseSourceFolderStructure | switch | No | ソースのファイルパスを維持 | - |
| IncludeSupportDbs | switch | No | ReportServer等サポートDBを含む | - |
| SetSourceReadOnly | switch | No | 移行前にソースDBを読み取り専用に | - |
| SetSourceOffline | switch | No | 移行前にソースDBをオフラインに | - |
| UseLastBackup | switch | No | 既存バックアップを使用 | SharedPathと排他 |
| Continue | switch | No | NORECOVERY状態のDBにログ適用 | UseLastBackup必須 |
| KeepCDC | switch | No | CDC構成を維持 | - |
| KeepReplication | switch | No | レプリケーション設定を維持 | - |
| MasterKeyPassword | SecureString | No | マスターキーパスワード | 証明書移行時に使用 |
| Exclude | string[] | No | 移行から除外する項目 | ValidateSetで制限 |
| ExcludeSaRename | switch | No | saアカウント名変更をスキップ | - |
| DisableJobsOnDestination | switch | No | 移行後にジョブを無効化 | - |
| DisableJobsOnSource | switch | No | ソースのジョブを無効化 | - |
| AzureCredential | string | No | Azure Storage資格情報名 | - |
| Force | switch | No | 既存オブジェクトを上書き | - |
| EnableException | switch | No | 例外を有効化 | - |

### 入力データソース

- ソースSQL Serverインスタンスの全サーバーオブジェクト
- ソースSQL Serverインスタンスの全ユーザーデータベース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Copy-DbaDatabase出力 | Object | データベース移行結果（-Exclude Databasesでない場合） |

### 出力先

PowerShellパイプライン（Copy-DbaDatabase実行時のみ出力、その他はVerboseメッセージ）

## 処理フロー

### 処理シーケンス

```
1. Begin ブロック
   └─ パラメータ検証
       ├─ BackupRestore/DetachAttachのいずれかが必要（Databases除外でない場合）
       ├─ BackupRestoreとDetachAttachの排他チェック
       ├─ BackupRestore時のSharedPath/UseLastBackupチェック
       └─ Continue使用時のUseLastBackup必須チェック

2. Process ブロック - 移行処理の順次実行
   └─ 各Excludeフラグをチェックしながら以下を実行:
       01. Copy-DbaSpConfigure
       02. Copy-DbaDbCertificate (master)
       03. Copy-DbaCustomError
       04. Copy-DbaServerRole
       05. Copy-DbaCredential
       06. Copy-DbaDbMail
       07. Copy-DbaRegServer
       08. Copy-DbaBackupDevice
       09. Copy-DbaInstanceTrigger
       10. Copy-DbaDatabase
       11. Copy-DbaLogin
       12. Update-SqlDbOwner
       13. Copy-DbaLinkedServer
       14. Copy-DbaDataCollector
       15. Copy-DbaInstanceAudit
       16. Copy-DbaInstanceAuditSpecification
       17. Copy-DbaEndpoint
       18. Copy-DbaPolicyManagement
       19. Copy-DbaResourceGovernor
       20. Copy-DbaSystemDbUserObject
       21. Copy-DbaXESession
       22. Copy-DbaAgentServer
       23. Copy-DbaStartupProcedure
       24. Copy-DbaExtendedStoredProcedure

3. End ブロック
   └─ 総実行時間の計算と出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ検証}
    B -->|NG| C[エラー終了]
    B -->|OK| D[ソースサーバー接続]
    D --> E{SpConfigure除外?}
    E -->|No| F[Copy-DbaSpConfigure]
    E -->|Yes| G{MasterCertificates除外?}
    F --> G
    G -->|No| H[Copy-DbaDbCertificate]
    G -->|Yes| I{CustomErrors除外?}
    H --> I
    I -->|No| J[Copy-DbaCustomError]
    I -->|Yes| K[...以降同様のパターン...]
    J --> K
    K --> L{Databases除外?}
    L -->|No| M[Copy-DbaDatabase]
    L -->|Yes| N{Logins除外?}
    M --> N
    N -->|No| O[Copy-DbaLogin]
    N -->|Yes| P[...以降同様のパターン...]
    O --> P
    P --> Q[終了時刻・経過時間出力]
    Q --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 移行方式必須 | Databases除外でない場合、BackupRestoreまたはDetachAttach必須 | 常に |
| BR-02 | 方式排他 | BackupRestoreとDetachAttachは同時使用不可 | 常に |
| BR-03 | 共有パス必須 | BackupRestore使用時、SharedPathまたはUseLastBackup必須 | BackupRestore時 |
| BR-04 | 再アタッチ必須 | 複数Destinationへのデタッチ移行時はReattach必須 | DetachAttach + 複数宛先 |
| BR-05 | Continue依存 | ContinueはUseLastBackupと共に使用 | Continue指定時 |
| BR-06 | Azure制限 | Azure URLはBackupRestoreのみサポート | SharedPath使用時 |

### 計算ロジック

- 総実行時間: `$elapsed.Elapsed.toString().Split(".")[0]`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 読取/作成 | 各種システムオブジェクト | SELECT/CREATE | 各サブコマンドで実行 |
| バックアップ | ユーザーDB | BACKUP | Copy-DbaDatabase (BackupRestore) |
| リストア | ユーザーDB | RESTORE | Copy-DbaDatabase (BackupRestore) |
| デタッチ | ユーザーDB | sp_detach_db | Copy-DbaDatabase (DetachAttach) |
| アタッチ | ユーザーDB | CREATE DATABASE FOR ATTACH | Copy-DbaDatabase (DetachAttach) |

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

各サブコマンドの詳細は個別の機能設計書を参照

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | 移行方式未指定 | BackupRestoreまたはDetachAttach指定 |
| - | パラメータエラー | 方式の重複指定 | いずれか一方のみ指定 |
| ConnectionError | 接続エラー | ソースサーバー接続失敗 | 接続情報確認 |

### リトライ仕様

各サブコマンドは独立して実行され、1つの失敗は他に影響しない

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

各サブコマンドは独立したトランザクションとして実行される。全体をロールバックする仕組みはない。

## パフォーマンス要件

特に定義なし。移行対象の規模に応じて処理時間が変動する。経過時間は終了時にVerboseで出力される。

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

- 各サブコマンドで必要な権限が異なる（一般的にsysadmin推奨）
- 資格情報はPSCredentialオブジェクトで安全に取り扱う
- MasterKeyPasswordはSecureStringで受け取る

## 備考

- WhatIf/Confirmパラメータによる事前確認が可能
- 各移行項目は-Excludeパラメータで個別にスキップ可能
- Verboseスイッチで詳細な進捗メッセージを確認可能
- 開始時刻・終了時刻・総経過時間が出力される

---

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

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

### 推奨読解順序

#### Step 1: コマンドの概要を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | コメントベースヘルプ（1-240行目）で機能の目的と全移行項目を把握 |

**読解のコツ**: .DESCRIPTIONセクションで移行される全オブジェクト種別とExcludeパラメータの対応を確認できる。

#### Step 2: パラメータ定義を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | paramブロック（241-271行目）で多数のパラメータ構造を確認 |

**主要処理フロー**:
- **258行目**: ValidateSetでExcludeの有効値を定義（24種類）
- **263-265行目**: UseLastBackup, KeepCDC, KeepReplicationのスイッチ

#### Step 3: パラメータ検証を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | beginブロック（273-309行目）で相互依存バリデーションを確認 |

**主要処理フロー**:
- **276-281行目**: Databases除外でない場合、BackupRestore/DetachAttach必須チェック
- **282-297行目**: 各種パラメータの排他・依存チェック
- **306-308行目**: Stopwatch開始

#### Step 4: 移行処理の実行順序を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | processブロック（311-548行目）で各サブコマンドの呼び出し順序を確認 |

**主要処理フロー**:
- **357-361行目**: SpConfigure移行
- **363-368行目**: master証明書移行
- **412-457行目**: データベース移行（BackupRestore/DetachAttach分岐）
- **459-464行目**: ログイン移行
- **530-535行目**: AgentServer移行

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

```
Start-DbaMigration
    │
    ├─ Connect-DbaInstance (ソース接続)
    │
    ├─ Copy-DbaSpConfigure
    ├─ Copy-DbaDbCertificate
    ├─ Copy-DbaCustomError
    ├─ Copy-DbaServerRole
    ├─ Copy-DbaCredential
    ├─ Copy-DbaDbMail
    ├─ Copy-DbaRegServer
    ├─ Copy-DbaBackupDevice
    ├─ Copy-DbaInstanceTrigger
    │
    ├─ Copy-DbaDatabase ───────▶ パイプライン出力
    │       ├─ BackupRestore分岐
    │       └─ DetachAttach分岐
    │
    ├─ Copy-DbaLogin
    ├─ Update-SqlDbOwner
    ├─ Copy-DbaLinkedServer
    ├─ Copy-DbaDataCollector
    ├─ Copy-DbaInstanceAudit
    ├─ Copy-DbaInstanceAuditSpecification
    ├─ Copy-DbaEndpoint
    ├─ Copy-DbaPolicyManagement
    ├─ Copy-DbaResourceGovernor
    ├─ Copy-DbaSystemDbUserObject
    ├─ Copy-DbaXESession
    ├─ Copy-DbaAgentServer
    ├─ Copy-DbaStartupProcedure
    └─ Copy-DbaExtendedStoredProcedure
```

### データフロー図

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

Source Instance ─────────────▶ 各Copy-Dba*コマンド ──────────▶ Verbose Messages
        │                           │
        │                           ▼
        └──────────────────▶ Copy-DbaDatabase ──────────────▶ Pipeline Output
                                    │
                                    ▼
                           Destination Instance(s)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Start-DbaMigration.ps1 | `public/Start-DbaMigration.ps1` | ソース | メインコマンド実装 |
| Copy-DbaSpConfigure.ps1 | `public/Copy-DbaSpConfigure.ps1` | ソース | sp_configure移行 |
| Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | ソース | データベース移行 |
| Copy-DbaLogin.ps1 | `public/Copy-DbaLogin.ps1` | ソース | ログイン移行 |
| Copy-DbaAgentServer.ps1 | `public/Copy-DbaAgentServer.ps1` | ソース | Agentサーバー移行 |
| Copy-DbaInstanceAuditSpecification.ps1 | `public/Copy-DbaInstanceAuditSpecification.ps1` | ソース | 監査仕様移行 |
