# 機能設計書 191-New-DbaDbTransfer

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`New-DbaDbTransfer`機能の設計仕様を記載する。この機能は、SQL Serverインスタンス間でデータベースオブジェクトをコピーするための構成済みSMO Transferオブジェクトを作成する。

### 本機能の処理概要

**業務上の目的・背景**：データベースの移行、環境のリフレッシュ、選択的なオブジェクト配布といった業務シナリオにおいて、SQL Serverインスタンス間でデータベースオブジェクト（テーブル、ビュー、ストアドプロシージャ、ユーザー等）をコピーする必要がある。本機能は、これらの転送操作を構成するためのオブジェクトを作成し、柔軟な転送設定を可能にする。

**機能の利用シーン**：
- 開発環境から本番環境へのスキーマデプロイ
- データベースの異なるインスタンス間での移行作業
- テスト環境のセットアップ（スキーマのみ、またはデータのみの転送）
- 特定のオブジェクトのみを選択的に別サーバーに配布する場合

**主要な処理内容**：
1. ソースSQL Serverインスタンスに接続し、ソースデータベースを取得
2. SMO Transferオブジェクトを生成し、各種パラメータに基づいて構成
3. パイプライン入力された個別オブジェクトをObjectListに追加
4. バッチサイズ、タイムアウト、コピー対象オブジェクト種別を設定
5. 宛先接続情報（SSL/TLS設定含む）を構成
6. スキーマのみ/データのみオプションを反映
7. 構成済みTransferオブジェクトを返却（実行はInvoke-DbaDbTransferまたは.TransferData()で行う）

**関連システム・外部連携**：SMO（SQL Server Management Objects）を使用してSQL Serverに接続し、転送操作を実行する。Microsoft.Data.SqlClientを使用して宛先接続を構成する。

**権限による制御**：ソースサーバーでの読み取り権限、宛先サーバーでのオブジェクト作成権限が必要。SQLCredentialパラメータにより、SQL Server認証やWindows認証を選択可能。

## 関連画面

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

## 機能種別

データ連携 / オブジェクト生成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | No | ソースSQL Serverインスタンス名 | Test-Boundでチェック |
| SqlCredential | PSCredential | No | ソースインスタンスへの認証情報 | - |
| DestinationSqlInstance | DbaInstanceParameter | No | 宛先SQL Serverインスタンス名 | - |
| DestinationSqlCredential | PSCredential | No | 宛先インスタンスへの認証情報 | SQL Server認証のみサポート |
| Database | string | No | ソースデータベース名 | Test-Boundでチェック |
| DestinationDatabase | string | No | 宛先データベース名（デフォルト: ソースと同じ） | - |
| BatchSize | int | No | バルクコピーのバッチサイズ（デフォルト: 50000） | - |
| BulkCopyTimeOut | int | No | バルクコピーのタイムアウト秒（デフォルト: 5000） | - |
| ScriptingOption | ScriptingOptions | No | スクリプティングオプションオブジェクト | New-DbaScriptingOptionで作成 |
| InputObject | NamedSmoObject[] | No | 転送対象の個別オブジェクト | パイプラインから受け取り |
| CopyAllObjects | switch | No | 全オブジェクトをコピー | - |
| CopyAll | string[] | No | コピーするオブジェクト種別の配列 | ValidateSetで制限 |
| SchemaOnly | switch | No | スキーマのみ転送（データなし） | - |
| DataOnly | switch | No | データのみ転送（スキーマなし） | - |
| EnableException | switch | No | 例外をスローするかどうか | - |

### 入力データソース

- パラメータ入力: SqlInstance、Database等の接続情報
- パイプライン入力: Get-DbaDbTable等から取得したSMOオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Transfer | Microsoft.SqlServer.Management.Smo.Transfer | 構成済みの転送オブジェクト |

### 出力先

PowerShellパイプラインへの出力。返却されたオブジェクトは`Invoke-DbaDbTransfer`にパイプで渡すか、`.TransferData()`メソッドを呼び出して実行する。

## 処理フロー

### 処理シーケンス

```
1. beginブロック: オブジェクトコレクション初期化
   └─ ArrayListの作成
2. processブロック: パイプライン入力処理
   ├─ SqlInstance未指定チェック
   ├─ Database未指定チェック
   └─ InputObjectをコレクションに追加
3. endブロック: Transferオブジェクト生成
   ├─ Get-DbaDatabaseでソースデータベース取得
   ├─ Transferオブジェクト作成
   ├─ ObjectListへの個別オブジェクト追加
   ├─ BatchSize、BulkCopyTimeOut設定
   ├─ CopyAllObjects、CopyAll設定
   ├─ ScriptingOption設定
   ├─ 宛先接続情報の構成
   │   ├─ SSL/TLS設定の継承
   │   ├─ 接続文字列の解析
   │   └─ ServerConnectionオブジェクト作成
   ├─ SchemaOnly/DataOnly設定
   └─ Transferオブジェクト返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance指定?}
    B -->|No| C[エラー終了]
    B -->|Yes| D{Database指定?}
    D -->|No| C
    D -->|Yes| E[InputObjectをコレクションに追加]
    E --> F[Get-DbaDatabaseでソースDB取得]
    F --> G{ソースDB存在?}
    G -->|No| C
    G -->|Yes| H[Transferオブジェクト作成]
    H --> I[ObjectList設定]
    I --> J[BatchSize/TimeOut設定]
    J --> K[CopyAll設定]
    K --> L[宛先接続情報構成]
    L --> M[SchemaOnly/DataOnly設定]
    M --> N[Transferオブジェクト返却]
    N --> O[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | ソース接続必須 | SqlInstanceパラメータは必須 | 常時 |
| BR-002 | データベース必須 | Databaseパラメータは必須 | 常時 |
| BR-003 | 複数DB禁止 | 1つのデータベースのみ処理可能 | 常時 |
| BR-004 | SSL継承 | ソース接続のSSL/TLS設定を宛先に継承 | 常時 |
| BR-005 | デフォルトDB | 宛先DB未指定時はソースDB名を使用 | DestinationDatabase未指定時 |

### 計算ロジック

特に計算処理は行わない。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Get-DbaDatabase呼び出し | - | SELECT | ソースデータベースのメタデータ取得 |

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

本機能はTransferオブジェクトの構成のみを行い、実際のデータベース操作は実行しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | SqlInstance未指定 | SqlInstanceパラメータを指定 |
| - | Stop-Function | Database未指定 | Databaseパラメータを指定 |
| - | Stop-Function | ソースDB取得失敗 | 接続情報を確認 |
| - | Stop-Function | ソースDB未存在 | データベース名を確認 |
| - | Stop-Function | 複数DB取得 | Database指定を一意にする |
| - | Stop-Function | 空オブジェクト入力 | 有効なオブジェクトを指定 |

### リトライ仕様

本機能にリトライ機能はない。

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

本機能はオブジェクト構成のみを行うため、トランザクション処理は発生しない。実際の転送実行時のトランザクションはSMO Transferオブジェクトに依存する。

## パフォーマンス要件

- BatchSizeのデフォルト値50000行は、メモリ使用量と転送速度のバランスを考慮した値
- BulkCopyTimeOutのデフォルト値5000秒は、大規模テーブルの転送を考慮した値

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

- SqlCredentialおよびDestinationSqlCredentialでSQL Server認証情報を安全に渡す
- 宛先接続でのパスワードはSecureStringから取得したネットワーク資格情報を使用
- SSL/TLS設定はソース接続から継承され、セキュアな接続を維持

## 備考

- 本機能はTransferオブジェクトを返すのみで、実際の転送は実行しない
- 転送実行にはInvoke-DbaDbTransferを使用するか、返却オブジェクトの.TransferData()メソッドを呼び出す

---

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

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

### 推奨読解順序

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

まず、SMO Transferオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Transfer Class | Microsoft.SqlServer.Management.Smo | Transferオブジェクトのプロパティ構造 |

**読解のコツ**: SMO TransferオブジェクトはSQL Serverオブジェクトの転送を制御するクラスで、CopyAllプロパティ群、Options、DestinationServer等の設定を持つ。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | 関数定義とパラメータ構造 |

**主要処理フロー**:
1. **151-153行目**: beginブロックでArrayList初期化
2. **154-170行目**: processブロックでパイプライン入力処理
3. **172-272行目**: endブロックでTransferオブジェクト構成と返却

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | パラメータバリデーションとデフォルト値 |

**主要処理フロー**:
- **127-150行目**: param()ブロックでパラメータ定義
- **133行目**: DestinationDatabaseのデフォルト値設定
- **134-135行目**: BatchSizeとBulkCopyTimeOutのデフォルト値

#### Step 4: Transferオブジェクト構成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | Transferオブジェクトの構成処理 |

**主要処理フロー**:
- **187行目**: Transferオブジェクト作成
- **188-190行目**: ObjectListへのオブジェクト追加
- **191-196行目**: プロパティ設定
- **199-267行目**: 宛先接続情報の構成
- **268-269行目**: SchemaOnly/DataOnly設定

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

```
New-DbaDbTransfer
    │
    ├─ Test-Bound (内部関数)
    │      └─ パラメータ指定チェック
    │
    ├─ Get-DbaDatabase
    │      └─ ソースデータベース取得
    │
    ├─ New-Object Microsoft.SqlServer.Management.Smo.Transfer
    │      └─ Transferオブジェクト作成
    │
    ├─ New-Object Microsoft.Data.SqlClient.SqlConnectionStringBuilder
    │      └─ 接続文字列構築
    │
    └─ New-Object Microsoft.SqlServer.Management.Common.ServerConnection
           └─ 宛先ServerConnection作成
```

### データフロー図

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

SqlInstance ───────────────┐
Database ──────────────────┤
DestinationSqlInstance ────┤
DestinationSqlCredential ──┼──▶ New-DbaDbTransfer ──────────────▶ Transfer Object
InputObject (pipeline) ────┤      │
CopyAll ───────────────────┤      ├─ Get-DbaDatabase
BatchSize ─────────────────┤      ├─ Transferオブジェクト構成
ScriptingOption ───────────┘      └─ 宛先接続設定
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | ソース | メイン関数定義 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | ソースDB取得 |
| New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | ソース | ScriptingOption生成 |
| Invoke-DbaDbTransfer.ps1 | `public/Invoke-DbaDbTransfer.ps1` | ソース | 転送実行（関連機能） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
