# 機能設計書 171-Invoke-DbaDbTransfer

## 概要

本ドキュメントは、dbatools PowerShellモジュールのInvoke-DbaDbTransfer関数の機能設計を定義する。SMO Transferオブジェクトを使用してSQL Serverインスタンス間またはデータベース間でオブジェクトとデータを転送する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：データベースのマイグレーション、環境間の同期、選択的なオブジェクトデプロイメントにおいて、フルデータベースリストアを行わずに特定のオブジェクトやデータをコピーする必要がある場面で使用される。開発環境から本番環境へのスキーマ変更のデプロイ、環境のリフレッシュ、部分的なデータベース移行など、DBA業務の効率化を目的とする。

**機能の利用シーン**：
- 開発環境から本番環境へストアドプロシージャやビューをデプロイする場合
- データウェアハウスのリフレッシュでテーブルとビューのみをコピーする場合
- 新環境のセットアップでスキーマのみを転送し、データは別途投入する場合
- 移行前にスクリプトをレビューするためにT-SQLスクリプトを生成する場合

**主要な処理内容**：
1. 入力パラメータまたはInputObjectからSMO Transferオブジェクトを取得/生成
2. DataTransferEventイベントハンドラを登録して転送進捗をキャプチャ
3. ScriptOnlyモードの場合はScriptTransfer()でT-SQLスクリプトを生成
4. 通常モードの場合はTransferData()で実際のオブジェクト・データ転送を実行
5. 転送結果（ステータス、経過時間、ログ）をPSCustomObjectとして出力

**関連システム・外部連携**：SQL Server Management Objects (SMO) のTransferクラスを使用。ソースおよび宛先のSQL Serverインスタンスへの接続が必要。

**権限による制御**：宛先サーバーでオブジェクトを作成・変更するための適切な権限が必要。データベースオーナー（db_owner）またはddl_admin以上の権限が推奨される。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 57 | データベース転送 | 主機能 | データベースオブジェクトの転送 |

## 機能種別

データ連携 / オブジェクト転送

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | No | ソースSQL Serverインスタンス名 | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | ソースへの接続資格情報 | - |
| DestinationSqlInstance | DbaInstanceParameter | No | 宛先SQL Serverインスタンス名 | 有効なインスタンス名 |
| DestinationSqlCredential | PSCredential | No | 宛先への接続資格情報 | - |
| Database | string | No | ソースデータベース名 | 存在するデータベース名 |
| DestinationDatabase | string | No | 宛先データベース名（デフォルト: ソースと同名） | - |
| BatchSize | int | No | バルクコピーのバッチサイズ（デフォルト: 50000） | 正の整数 |
| BulkCopyTimeOut | int | No | バルクコピーのタイムアウト秒数（デフォルト: 5000） | 正の整数 |
| ScriptingOption | ScriptingOptions | No | カスタムスクリプティングオプション | - |
| InputObject | Transfer | No | 事前設定済みSMO Transferオブジェクト | ValueFromPipeline |
| CopyAllObjects | switch | No | 全データベースオブジェクトを転送 | - |
| CopyAll | string[] | No | 転送するオブジェクトタイプの配列 | ValidateSet |
| SchemaOnly | switch | No | スキーマのみ転送（データなし） | - |
| DataOnly | switch | No | データのみ転送（スキーマなし） | - |
| ScriptOnly | switch | No | スクリプト生成のみ（実行しない） | - |
| EnableException | switch | No | 例外をスローするか | - |

### 入力データソース

- SqlInstanceパラメータで指定されたソースSQL Serverインスタンス
- New-DbaDbTransferで事前作成されたTransferオブジェクト（パイプライン入力）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| SourceInstance | string | ソースSQL Serverインスタンス名 |
| SourceDatabase | string | ソースデータベース名 |
| DestinationInstance | string | 宛先SQL Serverインスタンス名 |
| DestinationDatabase | string | 宛先データベース名 |
| Status | string | 転送ステータス（Success） |
| Elapsed | prettytimespan | 転送の経過時間 |
| Log | string[] | DataTransferEventからのイベントメッセージ配列 |

### 出力先

- 標準出力（パイプライン）にPSCustomObjectを出力
- ScriptOnlyモードの場合はT-SQLスクリプト文字列の配列を出力

## 処理フロー

### 処理シーケンス

```
1. beginブロック: New-DbaDbTransferのパラメータキーを取得
   └─ 共通パラメータを除外したパラメータリスト準備

2. processブロック開始
   └─ InputObjectが指定されているか判定

3. Transferオブジェクト取得
   ├─ InputObject指定時: そのまま使用
   └─ 未指定時: パラメータを渡してNew-DbaDbTransferを呼び出し

4. イベントハンドラ登録
   └─ DataTransferEventをRegister-ObjectEventで登録

5. ストップウォッチ開始
   └─ 経過時間計測用

6. ShouldProcess確認
   └─ WhatIfモードの場合はここで終了

7. 転送実行
   ├─ ScriptOnly指定時: ScriptTransfer()でスクリプト生成
   └─ 通常時: TransferData()でデータ転送

8. 結果オブジェクト構築・出力
   └─ PSCustomObjectとしてパイプライン出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{InputObject<br/>指定あり?}
    B -->|Yes| C[InputObjectを<br/>Transferとして使用]
    B -->|No| D[パラメータ抽出]
    D --> E[New-DbaDbTransfer<br/>呼び出し]
    C --> F[DataTransferEvent<br/>ハンドラ登録]
    E --> F
    F --> G[ストップウォッチ開始]
    G --> H{ShouldProcess?}
    H -->|No| I[終了]
    H -->|Yes| J{ScriptOnly?}
    J -->|Yes| K[ScriptTransfer実行]
    J -->|No| L[TransferData実行]
    K --> M[スクリプト配列を返却]
    L --> N{成功?}
    N -->|No| O[エラー処理]
    N -->|Yes| P[結果オブジェクト構築]
    M --> I
    O --> I
    P --> Q[PSCustomObject出力]
    Q --> I
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-171-01 | デフォルト宛先データベース | DestinationDatabaseが未指定の場合、ソースと同じデータベース名を使用 | DestinationDatabase未指定時 |
| BR-171-02 | バッチサイズデフォルト | BatchSizeのデフォルト値は50000行 | BatchSize未指定時 |
| BR-171-03 | タイムアウトデフォルト | BulkCopyTimeOutのデフォルト値は5000秒 | BulkCopyTimeOut未指定時 |
| BR-171-04 | スクリプトモード排他 | ScriptOnlyモードではTransferDataは実行されずスクリプトのみ生成 | ScriptOnly指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| オブジェクト転送 | 指定オブジェクト | INSERT/CREATE | 宛先DBにオブジェクトを作成 |
| データ転送 | 指定テーブル | INSERT | 宛先テーブルにデータを挿入 |

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

宛先データベースの指定されたオブジェクトに対して、SMO Transferオブジェクトが自動的にDDL/DMLを生成・実行する。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | ソースまたは宛先への接続失敗 | 接続情報を確認 |
| - | TransferError | 転送処理中のエラー | Stop-Functionでエラー詳細を出力 |
| - | PermissionError | 宛先での権限不足 | 適切な権限を付与 |

### リトライ仕様

リトライ機能は実装されていない。エラー発生時は処理を中断する。

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

SMO Transferオブジェクトがバッチ単位でトランザクション管理を行う。BatchSizeパラメータで制御。

## パフォーマンス要件

- BatchSizeを調整することで大規模テーブルの転送パフォーマンスを最適化
- BulkCopyTimeOutを適切に設定して長時間実行を許可

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

- SqlCredentialを使用した安全な認証をサポート
- Windows認証、SQL Server認証、Active Directory認証に対応
- 宛先サーバーでの適切な権限管理が必要

## 備考

- New-DbaDbTransferで事前にTransferオブジェクトをカスタマイズし、パイプラインで渡すことでより詳細な制御が可能
- CopyAllパラメータで転送するオブジェクトタイプを細かく指定可能

---

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

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

### 推奨読解順序

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

SMO Transferオブジェクトの構造と出力オブジェクトの形式を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbTransfer.ps1 | `public/Invoke-DbaDbTransfer.ps1` | 199-207行目: 出力PSCustomObjectの構造を確認 |

**読解のコツ**: PSCustomObjectの各プロパティが何を表すか理解することで、関数の出力仕様が明確になる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbTransfer.ps1 | `public/Invoke-DbaDbTransfer.ps1` | 関数全体の流れを把握 |

**主要処理フロー**:
1. **165-167行目**: beginブロックでNew-DbaDbTransferのパラメータキーを取得
2. **168-181行目**: processブロックでTransferオブジェクトの取得または生成
3. **182-186行目**: イベントハンドラ登録とストップウォッチ開始
4. **187-208行目**: ShouldProcess確認後、転送実行と結果出力

#### Step 3: 関連関数を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | Transferオブジェクトの生成ロジック |
| 3-2 | New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | スクリプティングオプションのカスタマイズ方法 |

**主要処理フロー**:
- **New-DbaDbTransfer**: SMO Transferオブジェクトを生成し、CopyAllObjectsやCopyAllパラメータに基づいてプロパティを設定

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

```
Invoke-DbaDbTransfer
    │
    ├─ New-DbaDbTransfer (InputObject未指定時)
    │      └─ Connect-DbaInstance
    │
    ├─ Register-ObjectEvent
    │      └─ DataTransferEventハンドラ
    │
    └─ Transfer.TransferData() / Transfer.ScriptTransfer()
           └─ SMO内部処理
```

### データフロー図

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

SqlInstance ─────────┐
DestinationSqlInstance ┼──▶ New-DbaDbTransfer ──▶ Transfer Object
Database ────────────┘
                                    │
                                    ▼
InputObject (パイプライン) ──▶ Invoke-DbaDbTransfer
                                    │
                    ┌───────────────┴───────────────┐
                    ▼                               ▼
              [ScriptOnly]                    [通常モード]
                    │                               │
                    ▼                               ▼
            ScriptTransfer()               TransferData()
                    │                               │
                    ▼                               ▼
            T-SQL Scripts[]               PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbTransfer.ps1 | `public/Invoke-DbaDbTransfer.ps1` | ソース | メイン関数 |
| New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | ソース | Transferオブジェクト生成 |
| New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | ソース | スクリプティングオプション生成 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
