# 機能設計書 358-Copy-DbaDatabase

## 概要

本ドキュメントは、SQL Serverデータベースをインスタンス間で移行する `Copy-DbaDatabase` コマンドの機能設計書である。

### 本機能の処理概要

本機能は、バックアップ/リストアまたはデタッチ/アタッチ方式を使用して、ソースSQL ServerインスタンスからデスティネーションSQL Serverインスタンスにユーザーデータベースを移行する。オンプレミスおよびAzure SQL Managed Instanceへの移行をサポートする。

**業務上の目的・背景**：データベース移行は、サーバーリプレース、環境構築、DR構成、クラウド移行など様々なシナリオで必要となる。手動での移行はバックアップ取得、ファイルコピー、リストア実行という複数ステップを要し、ミスが発生しやすい。本機能により、これらの手順を自動化し、複数データベース・複数デスティネーションへの一括移行を実現する。

**機能の利用シーン**：
- サーバー移行（ハードウェアリプレース）
- 開発/テスト環境へのデータベースコピー
- Azure SQL Managed Instanceへのクラウド移行
- DRサイトへのデータベースレプリケーション

**主要な処理内容**：
1. ソース/デスティネーションサーバーへの接続
2. 移行方式の決定（BackupRestore / DetachAttach）
3. データベースファイル構造の解析
4. バックアップ取得またはデタッチ実行
5. ファイル転送（DetachAttach時）またはバックアップファイル共有
6. リストアまたはアタッチ実行
7. 結果の出力

**関連システム・外部連携**：SQL Server Agent、Azure Blob Storage（Azure移行時）、ファイル共有（UNCパス）、BITS転送

**権限による制御**：sysadmin権限が必要。ファイル共有への読み書き権限、管理共有（$）へのアクセス権限（DetachAttach時）が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | PowerShellコンソール | 主画面 | コマンド実行および結果表示 |

## 機能種別

データ移行 / データベースコピー

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | No | ソースSQL Serverインスタンス | InputObjectまたはSourceが必要 |
| SourceSqlCredential | PSCredential | No | ソース認証情報 | - |
| Destination | DbaInstanceParameter[] | Yes | デスティネーションインスタンス（複数可） | - |
| DestinationSqlCredential | PSCredential | No | デスティネーション認証情報 | - |
| Database | Object[] | No | コピー対象データベース | システムDB不可 |
| ExcludeDatabase | Object[] | No | 除外データベース | - |
| AllDatabases | Switch | No | 全ユーザーDB対象 | - |
| BackupRestore | Switch | Yes* | バックアップ/リストア方式 | ParameterSet |
| DetachAttach | Switch | Yes* | デタッチ/アタッチ方式 | ParameterSet |
| SharedPath | String | No | バックアップファイル共有パス | BackupRestore時 |
| AzureCredential | String | No | Azure資格情報名 | Azure Blob使用時 |
| UseLastBackup | Switch | No | 既存バックアップを使用 | BackupRestore時 |
| WithReplace | Switch | No | 既存DB上書き | - |
| NoRecovery | Switch | No | NORECOVERYモード | - |
| NoBackupCleanup | Switch | No | バックアップ削除しない | - |
| NumberFiles | Int | No | バックアップファイル数 | デフォルト3 |
| Reattach | Switch | No | ソースに再アタッチ | DetachAttach時 |
| SetSourceReadOnly | Switch | No | ソース読み取り専用化 | - |
| SetSourceOffline | Switch | No | ソースオフライン化 | - |
| ReuseSourceFolderStructure | Switch | No | ソースフォルダ構造を維持 | - |
| NewName | String | No | 新しいDB名 | 単一DB時のみ |
| Prefix | String | No | DB名プレフィックス | - |
| KeepCDC | Switch | No | CDC設定を維持 | - |
| KeepReplication | Switch | No | レプリケーション設定維持 | - |
| IncludeSupportDbs | Switch | No | サポートDB含む | - |
| InputObject | Database[] | No | パイプライン入力 | - |
| Force | Switch | No | 強制実行 | - |
| EnableException | Switch | No | 例外制御 | - |

### 入力データソース

- ソースサーバーのデータベースコレクション（SMO）
- バックアップ履歴（UseLastBackup時）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作日時 |
| SourceServer | String | ソースサーバー名 |
| DestinationServer | String | デスティネーションサーバー名 |
| Name | String | データベース名 |
| DestinationDatabase | String | デスティネーションDB名 |
| Type | String | 移行タイプ |
| Status | String | 結果（Successful / Skipped / Failed） |
| Notes | String | 追加情報 |

### 出力先

- PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   ├─ BackupRestore: SharedPathまたはUseLastBackupが必要
   ├─ DetachAttach: 複数デスティネーション時はReattach必要
   └─ Azure使用時: 資格情報チェック

2. ソースサーバー接続
   └─ Connect-DbaInstance

3. データベースリスト構築
   ├─ AllDatabases / Database パラメータ処理
   ├─ ExcludeDatabase 除外
   └─ システムDB (master, msdb, tempdb) 除外

4. デスティネーションループ開始

5. デスティネーションサーバー接続
   └─ Connect-DbaInstance

6. データベースループ開始

7. 事前チェック
   ├─ ミラーリング/AG参加チェック
   └─ レプリケーション参加チェック

8. 移行方式別処理
   ├─ BackupRestore:
   │   ├─ Backup-DbaDatabase または UseLastBackup
   │   ├─ ファイルパスの解決
   │   └─ Restore-DbaDatabase
   └─ DetachAttach:
       ├─ sp_detach_db 実行
       ├─ BITSまたはCopy-Item でファイル転送
       └─ sp_attach_db 実行

9. 後処理
   ├─ バックアップファイル削除（オプション）
   └─ ソース再アタッチ（Reattach時）

10. 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ検証}
    B -->|エラー| C[終了]
    B -->|OK| D[ソースサーバー接続]
    D --> E[データベースリスト構築]
    E --> F[デスティネーションループ]
    F --> G[デスティネーション接続]
    G --> H[データベースループ]
    H --> I{事前チェック}
    I -->|NG| J[Skipped]
    I -->|OK| K{BackupRestore?}
    K -->|Yes| L[バックアップ取得]
    K -->|No| M[デタッチ実行]
    L --> N[リストア実行]
    M --> O[ファイル転送]
    O --> P[アタッチ実行]
    N --> Q{成功?}
    P --> Q
    Q -->|Yes| R[Successful]
    Q -->|No| S[Failed]
    J --> T{次のDB?}
    R --> T
    S --> T
    T -->|Yes| H
    T -->|No| U{次のデスティネーション?}
    U -->|Yes| F
    U -->|No| V[後処理]
    V --> C
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムDB不可 | master, msdb, tempdbは移行不可 | 常時 |
| BR-002 | 方式指定必須 | BackupRestoreまたはDetachAttachが必須 | 常時 |
| BR-003 | SharedPath必須 | BackupRestore時はSharedPathまたはUseLastBackup必須 | BackupRestore時 |
| BR-004 | Reattach必須 | DetachAttach + 複数デスティネーション時はReattach必須 | 複数デスティネーション時 |
| BR-005 | Copy-Only | デフォルトでCopy-Onlyバックアップ | BackupRestore時 |

### 計算ロジック

- NumberFiles: バックアップファイル分割数（デフォルト3）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| バックアップ | 対象DB | BACKUP DATABASE | フルバックアップ取得 |
| リストア | 対象DB | RESTORE DATABASE | データベース復元 |
| デタッチ | master | sp_detach_db | データベース切り離し |
| アタッチ | master | sp_attach_db | データベース接続 |

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

データベースレベルの操作のため、テーブル操作なし。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| NoSharedPath | 検証エラー | SharedPath/UseLastBackupなしでBackupRestore | Stop-Function |
| NoReattach | 検証エラー | 複数デスティネーションでDetachAttach + Reattachなし | Stop-Function |
| SystemDb | 検証エラー | システムDB指定 | Stop-Function、continue |
| MirroringEnabled | 状態エラー | ミラーリング有効 | Stop-Function、continue |
| BackupFailed | バックアップエラー | バックアップ失敗 | Failed出力、continue |
| RestoreFailed | リストアエラー | リストア失敗 | Failed出力、continue |
| DetachFailed | デタッチエラー | デタッチ失敗 | Failed出力、ソース再アタッチ |

### リトライ仕様

リトライ処理なし。BITSファイル転送失敗時はCopy-Itemにフォールバック。

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

各データベース移行は独立。失敗したデータベースがあっても他のデータベース移行は継続。

## パフォーマンス要件

- データベースサイズに比例した処理時間
- NumberFilesによる並列バックアップ
- ネットワーク帯域による転送時間

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

- sysadmin権限が必要
- ファイル共有への適切なアクセス権限
- Azure資格情報の事前作成（Azure使用時）
- 管理共有（C$等）へのアクセス権限（DetachAttach時）

## 備考

- 問題発生時は Backup-DbaDatabase | Restore-DbaDatabase の個別使用を推奨
- SQL Server 2000からSQL Server 2012以上への直接移行は不可

---

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

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

### 推奨読解順序

#### Step 1: パラメータ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | paramブロック（239-300行目）でParameterSetを確認 |

**読解のコツ**: DbBackupとDbAttachDetachの2つのParameterSetが存在。

#### Step 2: ヘルパー関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | Get-SqlFileStructure（333-488行目） |
| 2-2 | Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | Dismount-SqlDatabase（490-548行目） |
| 2-3 | Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | Mount-SqlDatabase（550-575行目） |
| 2-4 | Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | Start-SqlFileTransfer（577-636行目） |
| 2-5 | Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | Start-SqlDetachAttach（638-703行目） |

**主要処理フロー**:
1. **Get-SqlFileStructure**: データファイル/ログファイルの配置情報取得
2. **Dismount-SqlDatabase**: デタッチ実行（ミラーリング解除、AG削除含む）
3. **Mount-SqlDatabase**: アタッチ実行
4. **Start-SqlFileTransfer**: BITSによるファイル転送
5. **Start-SqlDetachAttach**: デタッチ→転送→アタッチの一連処理

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

```
Copy-DbaDatabase
    │
    ├─ Connect-DbaInstance (Source)
    │
    ├─ Connect-DbaInstance (Destination)
    │
    ├─【BackupRestore方式】
    │   ├─ Backup-DbaDatabase
    │   │      └─ Copy-Onlyバックアップ
    │   │
    │   └─ Restore-DbaDatabase
    │          └─ WithReplace/NoRecovery対応
    │
    └─【DetachAttach方式】
        ├─ Get-SqlFileStructure
        │      └─ ファイル配置情報収集
        │
        ├─ Dismount-SqlDatabase
        │      ├─ ミラーリング解除
        │      ├─ AG削除
        │      └─ sp_detach_db
        │
        ├─ Start-SqlFileTransfer
        │      ├─ Start-BitsTransfer
        │      └─ Copy-Item (フォールバック)
        │
        └─ Mount-SqlDatabase
               └─ sp_attach_db
```

### データフロー図

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

Source ───▶ Connect-DbaInstance
Database        │
                ▼
          データベースリスト構築
                │
Destination ───▶ Connect-DbaInstance
                │
          ┌─────┴─────┐
          ▼           ▼
   BackupRestore  DetachAttach
          │           │
          ▼           ▼
   バックアップ    デタッチ
   (Copy-Only)     │
          │        ▼
          │     ファイル転送
          │     (BITS/Copy-Item)
          │        │
          ▼        ▼
      リストア   アタッチ
          │        │
          └────┬───┘
               ▼
          MigrationObject ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaDatabase.ps1 | `public/Copy-DbaDatabase.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Backup-DbaDatabase.ps1 | `public/Backup-DbaDatabase.ps1` | ソース | バックアップ実行 |
| Restore-DbaDatabase.ps1 | `public/Restore-DbaDatabase.ps1` | ソース | リストア実行 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得 |
