# 機能設計書 31-Copy-DbaBackupDevice

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Copy-DbaBackupDevice`コマンドレットに関する機能設計書です。このコマンドは、SQL Serverインスタンス間でバックアップデバイスを移行するための機能を提供します。

### 本機能の処理概要

Copy-DbaBackupDeviceは、SQL Serverのバックアップデバイス定義と物理ファイルを、ソースインスタンスからターゲットインスタンスへコピーする機能を提供します。バックアップデバイスの論理定義だけでなく、実際の物理バックアップファイルも含めて転送を行います。

**業務上の目的・背景**：SQL Serverの移行やディザスタリカバリ環境の構築において、バックアップデバイスの構成を一貫して維持する必要があります。手動でのデバイス再作成は時間がかかりエラーが発生しやすいため、この機能により自動化された信頼性の高い移行を実現します。

**機能の利用シーン**：
- SQL Serverインスタンスの移行作業
- ディザスタリカバリサイトの構築
- 開発/テスト環境への本番バックアップデバイス構成のレプリケーション
- 複数サーバー間でのバックアップインフラストラクチャの標準化

**主要な処理内容**：
1. ソースSQL Serverインスタンスへの接続とバックアップデバイス一覧の取得
2. ターゲットSQL Serverインスタンスへの接続と既存デバイスの確認
3. デバイスのT-SQLスクリプト生成とパス置換処理
4. 物理バックアップファイルのBITSTransferによる転送
5. ターゲットインスタンスでのバックアップデバイス作成

**関連システム・外部連携**：
- Windows BITS (Background Intelligent Transfer Service)による大容量ファイル転送
- Windows管理共有(Admin shares)を使用したファイルアクセス

**権限による制御**：ソースおよびターゲットSQL Serverインスタンスでsysadmin権限が必要です。また、管理共有へのアクセス権限も必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | バックアップ管理 | 補助機能 | バックアップデバイスのコピー |

## 機能種別

データ連携 / 移行処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | SQL Server 2000以上、接続可能であること |
| SourceSqlCredential | PSCredential | No | ソースへの接続資格情報 | - |
| Destination | DbaInstanceParameter[] | Yes | ターゲットSQL Serverインスタンス（複数可） | SQL Server 2000以上、接続可能であること |
| DestinationSqlCredential | PSCredential | No | ターゲットへの接続資格情報 | - |
| BackupDevice | object[] | No | コピー対象のバックアップデバイス名 | ソースに存在するデバイス名であること |
| Force | switch | No | 既存デバイスを強制上書き | - |
| EnableException | switch | No | 例外処理を有効化 | - |
| WhatIf | switch | No | 実行せずに処理内容を表示 | - |
| Confirm | switch | No | 実行前に確認を求める | - |

### 入力データソース

- ソースSQL Serverインスタンスの`$server.BackupDevices`コレクション
- ソースサーバーの物理バックアップファイル（管理共有経由）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作実行日時 |
| SourceServer | string | ソースSQL Serverインスタンス名 |
| DestinationServer | string | ターゲットSQL Serverインスタンス名 |
| Name | string | バックアップデバイス名 |
| Type | string | "Backup Device"固定 |
| Status | string | Successful / Skipped / Failed |
| Notes | string | 追加情報（エラー詳細等） |

### 出力先

- PowerShellパイプライン（PSCustomObject）
- Select-DefaultViewにより整形された表示出力

## 処理フロー

### 処理シーケンス

```
1. プラットフォームチェック
   └─ Windows以外の場合はStop-Functionで終了

2. ソースインスタンス接続
   └─ Connect-DbaInstanceによる接続確立
   └─ BackupDevicesコレクション取得

3. 各ターゲットインスタンスに対して処理
   └─ ターゲットインスタンス接続
   └─ 既存デバイス一覧取得

4. 各バックアップデバイスに対して処理
   └─ フィルタリング（BackupDevice指定時）
   └─ 既存チェック
      ├─ 存在 + Force無し: スキップ
      └─ 存在 + Force有り: 既存デバイス削除

5. T-SQLスクリプト生成
   └─ Script()メソッドでスクリプト取得
   └─ サーバー名置換

6. 物理ファイル転送
   └─ ターゲットパス存在チェック
   └─ パスが存在しない場合はデフォルトバックアップディレクトリ使用
   └─ Start-BitsTransferによるファイル転送

7. デバイス作成
   └─ T-SQL実行
   └─ BackupDevices.Refresh()

8. 結果出力
   └─ PSCustomObject生成
   └─ Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Windows環境?}
    B -->|No| C[Stop-Function: Linux未サポート]
    B -->|Yes| D[ソースインスタンス接続]
    D --> E[BackupDevices取得]
    E --> F[各ターゲットインスタンスループ]
    F --> G[ターゲット接続]
    G --> H[各バックアップデバイスループ]
    H --> I{フィルタ条件一致?}
    I -->|No| H
    I -->|Yes| J{既存デバイス存在?}
    J -->|Yes| K{Force指定?}
    K -->|No| L[スキップ出力]
    K -->|Yes| M[既存デバイス削除]
    J -->|No| N[スクリプト生成]
    M --> N
    N --> O[パス存在チェック]
    O --> P{パス存在?}
    P -->|No| Q[デフォルトパス使用]
    P -->|Yes| R[BITSファイル転送]
    Q --> R
    R --> S[T-SQL実行でデバイス作成]
    S --> T[成功出力]
    T --> H
    L --> H
    H --> F
    F --> U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | Windows限定 | Linux環境では実行不可 | 常時 |
| BR-02 | 既存スキップ | Forceなしで既存デバイスはスキップ | 既存デバイス存在時 |
| BR-03 | パスフォールバック | ターゲットにパスがない場合はデフォルトバックアップディレクトリ使用 | パス不存在時 |
| BR-04 | 管理共有利用 | ファイル転送はAdmin shares経由 | ファイル転送時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| デバイス一覧取得 | sys.backup_devices | SELECT | ソースのバックアップデバイス定義取得 |
| デバイス削除 | sys.backup_devices | DELETE | Forceオプション時の既存デバイス削除 |
| デバイス作成 | sys.backup_devices | INSERT | sp_addumpdevice相当のT-SQL実行 |

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

#### sys.backup_devices

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, physical_location, type等 | ソースインスタンスから全デバイス取得 | SMO経由 |
| DELETE | 対象デバイス | -Force指定時にDrop()メソッド実行 | SMO経由 |
| INSERT | name, physical_location等 | Script()生成のT-SQL実行 | sp_addumpdevice相当 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | ソース/ターゲット接続失敗 | 接続情報確認、ネットワーク確認 |
| - | Platform | Linux環境での実行 | Windows環境で実行 |
| - | FileCopy | BITSTransfer失敗 | 管理共有アクセス権限確認 |
| - | Query | T-SQL実行失敗 | sysadmin権限確認 |

### リトライ仕様

リトライ機能は実装されていません。各ターゲットインスタンスに対して-Continue付きでエラー継続処理されます。

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

バックアップデバイス作成操作は個別トランザクションで実行されます。一つのデバイス作成が失敗しても他のデバイスの処理は継続されます。

## パフォーマンス要件

BITSTransferを使用しているため、大容量ファイルの転送には時間がかかる場合があります。ネットワーク帯域幅と物理ファイルサイズに依存します。

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

- ソース/ターゲットインスタンスでsysadmin権限が必要
- Windows管理共有（C$等）へのアクセス権限が必要
- 資格情報はPSCredentialオブジェクトで安全に渡す
- WhatIfパラメータで事前確認が可能

## 備考

- Linuxはサポートされていないが、将来的に実装可能とのコメントあり（105-108行目）
- SupportsShouldProcessが実装されており、WhatIf/Confirmに対応

---

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

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

### 推奨読解順序

#### Step 1: 関数定義とパラメータを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaBackupDevice.ps1 | `public/Copy-DbaBackupDevice.ps1` | パラメータ定義（93-104行目）、CmdletBinding属性を確認 |

**読解のコツ**: PowerShellのAdvanced Functionパターンを理解することが重要。`[parameter(Mandatory)]`や`[switch]`型の使い方に注目。

#### Step 2: begin ブロックの初期化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaBackupDevice.ps1 | `public/Copy-DbaBackupDevice.ps1` | beginブロック（105-120行目）でのプラットフォームチェックと接続処理 |

**主要処理フロー**:
1. **106-109行目**: `$script:isWindows`によるプラットフォームチェック
2. **110-115行目**: `Connect-DbaInstance`でソース接続
3. **116-117行目**: バックアップデバイスコレクション取得

#### Step 3: process ブロックのメイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaBackupDevice.ps1 | `public/Copy-DbaBackupDevice.ps1` | processブロック（121-243行目）でのデバイスコピー処理 |

**主要処理フロー**:
- **123-128行目**: ターゲットインスタンスへの接続
- **132-147行目**: デバイスフィルタリングとステータスオブジェクト初期化
- **149-171行目**: 既存デバイスのチェックとForce処理
- **173-184行目**: T-SQLスクリプト生成とサーバー名置換
- **188-224行目**: パス確認とBITSTransfer実行
- **226-240行目**: デバイス作成とRefresh

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

```
Copy-DbaBackupDevice
    │
    ├─ Connect-DbaInstance (ソース接続)
    │      └─ SMO Server オブジェクト取得
    │
    ├─ foreach $destinstance
    │      │
    │      ├─ Connect-DbaInstance (ターゲット接続)
    │      │
    │      └─ foreach $currentBackupDevice
    │             │
    │             ├─ BackupDevice.Drop() (Force時)
    │             │
    │             ├─ BackupDevice.Script()
    │             │      └─ T-SQL生成
    │             │
    │             ├─ Test-DbaPath
    │             │      └─ パス存在確認
    │             │
    │             ├─ Join-AdminUnc
    │             │      └─ 管理共有パス構築
    │             │
    │             ├─ Start-BitsTransfer
    │             │      └─ ファイル転送
    │             │
    │             └─ $destServer.Query($sql)
    │                    └─ デバイス作成
    │
    └─ Select-DefaultView
           └─ 出力整形
```

### データフロー図

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

$Source ────────────▶ Connect-DbaInstance ─────▶ $sourceServer
                             │
$sourceServer ──────▶ .BackupDevices ─────────▶ $serverBackupDevices
                             │
$Destination ───────▶ Connect-DbaInstance ─────▶ $destServer
                             │
$currentBackupDevice ▶ .Script() ─────────────▶ $sql (T-SQL)
                             │
PhysicalLocation ───▶ Join-AdminUnc ──────────▶ $sourcepath / $destPath
                             │
$sourcepath ────────▶ Start-BitsTransfer ─────▶ ファイル転送
                             │
$sql ───────────────▶ $destServer.Query() ────▶ デバイス作成
                             │
                             └────────────────────▶ PSCustomObject
                                                   (Status, Notes等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaBackupDevice.ps1 | `public/Copy-DbaBackupDevice.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ヘルパー |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス存在確認ヘルパー |
| Select-DefaultView.ps1 | `internal/functions/Select-DefaultView.ps1` | ソース | 出力整形ヘルパー |
