# 画面設計書 57-データベース転送

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるデータベース転送（Database Transfer）機能の設計仕様を記載したものです。SMO Transferオブジェクトを使用して、SQL Serverインスタンス間またはデータベース間でオブジェクトとデータを転送する機能を提供します。

### 本画面の処理概要

本機能は、SMO（SQL Server Management Objects）のTransfer機能を使用して、データベースオブジェクト（テーブル、ビュー、ストアドプロシージャ、ユーザー等）およびテーブルデータをSQL Serverインスタンス間で転送するPowerShellコマンド群を提供します。フルリストアを行わずに選択的なオブジェクトデプロイメントや環境同期が可能です。

**業務上の目的・背景**：データベース移行、環境同期、選択的なオブジェクトデプロイメントなど、データベース全体のリストアが適切でないシナリオで必要となります。特定のテーブルやプロシージャのみを別のインスタンスにコピーしたり、開発環境から本番環境へのスキーマ同期を行う際に有用です。スキーマのみ、データのみ、または両方の転送をサポートし、スクリプト生成機能も提供します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `New-DbaDbTransfer` - 転送オブジェクトの作成
- `Invoke-DbaDbTransfer` - 転送の実行

**主要な操作・処理内容**：
1. 転送オブジェクトの構成（対象オブジェクト、転送方法の指定）
2. スキーマのみ、データのみ、または両方の転送モード選択
3. 転送の実行またはスクリプト生成
4. バッチサイズとタイムアウトの制御
5. 転送結果の取得

**画面遷移**：本機能はCLIコマンドであり、New-DbaDbTransferで作成したTransferオブジェクトをInvoke-DbaDbTransferにパイプで渡すか、直接Invoke-DbaDbTransferでパラメータ指定して実行できます。

**権限による表示制御**：転送にはソースデータベースへの読み取り権限、および宛先インスタンスでオブジェクトを作成・変更する権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 171 | Invoke-DbaDbTransfer | 主機能 | データベースオブジェクトの転送 |
| 191 | New-DbaDbTransfer | 補助機能 | 転送オブジェクトの作成 |

## 画面種別

実行（CLI）

## URL/ルーティング

PowerShellコマンドとして以下のコマンドレット名でアクセス:
- `New-DbaDbTransfer`
- `Invoke-DbaDbTransfer`

## 入出力項目

### New-DbaDbTransfer パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter | ソースSQL Serverインスタンス |
| SqlCredential | No | PSCredential | ソース認証用資格情報 |
| DestinationSqlInstance | No | DbaInstanceParameter | 宛先SQL Serverインスタンス |
| DestinationSqlCredential | No | PSCredential | 宛先認証用資格情報 |
| Database | No | string | ソースデータベース名 |
| DestinationDatabase | No | string | 宛先データベース名（省略時はソースと同じ） |
| BatchSize | No | int | バッチあたりの行数（デフォルト50,000） |
| BulkCopyTimeOut | No | int | バルクコピータイムアウト（デフォルト5000秒） |
| ScriptingOption | No | ScriptingOptions | スクリプトオプション |
| InputObject | No | NamedSmoObject[] | 転送するオブジェクト |
| CopyAllObjects | No | switch | すべてのオブジェクトを転送 |
| CopyAll | No | string[] | 転送するオブジェクトタイプ |
| SchemaOnly | No | switch | スキーマのみ転送 |
| DataOnly | No | switch | データのみ転送 |
| EnableException | No | switch | 例外を有効化 |

### Invoke-DbaDbTransfer パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter | ソースSQL Serverインスタンス |
| SqlCredential | No | PSCredential | ソース認証用資格情報 |
| DestinationSqlInstance | No | DbaInstanceParameter | 宛先SQL Serverインスタンス |
| DestinationSqlCredential | No | PSCredential | 宛先認証用資格情報 |
| Database | No | string | ソースデータベース名 |
| DestinationDatabase | No | string | 宛先データベース名 |
| BatchSize | No | int | バッチあたりの行数 |
| BulkCopyTimeOut | No | int | バルクコピータイムアウト |
| ScriptingOption | No | ScriptingOptions | スクリプトオプション |
| InputObject | No | Transfer | 転送オブジェクト（パイプライン入力） |
| CopyAllObjects | No | switch | すべてのオブジェクトを転送 |
| CopyAll | No | string[] | 転送するオブジェクトタイプ |
| SchemaOnly | No | switch | スキーマのみ転送 |
| DataOnly | No | switch | データのみ転送 |
| ScriptOnly | No | switch | スクリプトのみ生成（実行しない） |
| EnableException | No | switch | 例外を有効化 |

### CopyAllで指定可能なオブジェクトタイプ

- Tables, Views, StoredProcedures, UserDefinedFunctions
- UserDefinedDataTypes, UserDefinedTableTypes
- Users, Roles, Schemas
- PartitionSchemes, PartitionFunctions
- Sequences, Synonyms, DatabaseTriggers
- FullTextCatalogs, XmlSchemaCollections
- SqlAssemblies, ExternalDataSources, Logins など

## 表示項目

### Invoke-DbaDbTransfer 出力プロパティ（通常実行時）

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| SourceInstance | string | ソースインスタンス名 |
| SourceDatabase | string | ソースデータベース名 |
| DestinationInstance | string | 宛先インスタンス名 |
| DestinationDatabase | string | 宛先データベース名 |
| Status | string | 転送ステータス（Success） |
| Elapsed | prettytimespan | 経過時間 |
| Log | array | 転送イベントログ |

### Invoke-DbaDbTransfer 出力（ScriptOnly指定時）

- T-SQLスクリプト文字列配列

## イベント仕様

### 1-転送オブジェクト作成（New-DbaDbTransfer）

1. ソースデータベースの取得（Get-DbaDatabase）
2. SMO Transferオブジェクトの作成
3. InputObjectで指定されたオブジェクトの追加
4. CopyAllObjects/CopyAllに基づくプロパティ設定
5. 宛先接続情報の設定
6. SchemaOnly/DataOnlyフラグの設定
7. Transferオブジェクトの返却

### 2-転送実行（Invoke-DbaDbTransfer）

1. InputObjectがない場合はNew-DbaDbTransferを内部呼び出し
2. DataTransferEventのイベントハンドラ登録
3. ScriptOnly指定時はScriptTransfer()を実行してスクリプト返却
4. 通常実行時はTransferData()を実行
5. 経過時間の計測と結果オブジェクトの出力

## データベース更新仕様

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbTransfer | 宛先DB各テーブル | CREATE/INSERT | オブジェクト作成およびデータ挿入 |
| Invoke-DbaDbTransfer（DataOnly） | 宛先DB各テーブル | INSERT | データのみ挿入（オブジェクト作成なし） |
| Invoke-DbaDbTransfer（SchemaOnly） | 宛先DB | CREATE | オブジェクト作成のみ（データなし） |

### テーブル別更新項目詳細

転送されるオブジェクトとデータは、CopyAllまたはCopyAllObjectsパラメータの設定およびSchemaOnly/DataOnlyフラグに依存します。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Source instance was not specified | SqlInstance未指定 |
| MSG-002 | エラー | Source database was not specified | Database未指定 |
| MSG-003 | エラー | Database $Database not found on $SqlInstance | データベースが見つからない |
| MSG-004 | エラー | More than one database found | 複数のデータベースがマッチ |
| MSG-005 | エラー | Transfer failed | 転送失敗 |
| MSG-006 | エラー | Object is empty | パイプライン入力オブジェクトが空 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| ソースインスタンス未指定 | Stop-Functionで処理停止 |
| ソースデータベース未指定 | Stop-Functionで処理停止 |
| データベース取得失敗 | Stop-Functionで処理停止、詳細エラー出力 |
| 複数データベースマッチ | Stop-Functionで処理停止 |
| 転送失敗 | Stop-Functionで処理停止、エラーレコード出力 |

## 備考

- SMO Transferクラスはオブジェクトとデータの両方を転送可能
- SSL/TLS設定はソース接続から宛先に引き継がれる
- ScriptOnlyオプションでデプロイメントスクリプトの生成が可能
- New-DbaScriptingOptionで詳細なスクリプトオプションをカスタマイズ可能
- 大規模データ転送ではBatchSizeとBulkCopyTimeOutの調整を推奨

---

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

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

### 推奨読解順序

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

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Transfer | Microsoft.SqlServer.Management.Smo | Transferクラスのプロパティとメソッド |
| 1-2 | SMO ScriptingOptions | Microsoft.SqlServer.Management.Smo | スクリプトオプションのカスタマイズ |

**読解のコツ**: Transferオブジェクトは転送の構成を保持し、TransferData()またはScriptTransfer()で実行します。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | 転送オブジェクト作成のメインロジック |
| 2-2 | Invoke-DbaDbTransfer.ps1 | `public/Invoke-DbaDbTransfer.ps1` | 転送実行のメインロジック |

**主要処理フロー (New-DbaDbTransfer)**:
1. **行151-170**: パラメータ検証とオブジェクトコレクション構築
2. **行172-185**: ソースデータベースの取得
3. **行187-196**: Transferオブジェクト作成とプロパティ設定
4. **行199-267**: 宛先接続情報の設定
5. **行268-270**: SchemaOnly/DataOnlyフラグの設定

**主要処理フロー (Invoke-DbaDbTransfer)**:
1. **行165-180**: InputObjectがない場合のNew-DbaDbTransfer呼び出し
2. **行182-185**: DataTransferEventイベントハンドラ登録
3. **行187-197**: 転送実行（ScriptOnlyまたはTransferData）
4. **行199-207**: 結果オブジェクト出力

#### Step 3: 接続設定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` 行199-267 | 宛先接続設定ロジック |

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

```
New-DbaDbTransfer
    |
    +-- パラメータ検証
    |
    +-- Get-DbaDatabase (ソースDB取得)
    |
    +-- New-Object Transfer($sourceDb)
    |
    +-- Transferプロパティ設定
    |       +-- CopyAllObjects / CopyAll設定
    |       +-- BatchSize, BulkCopyTimeOut設定
    |       +-- ScriptingOptions設定
    |
    +-- 宛先接続設定
    |       +-- DestinationServerConnection作成
    |       +-- SSL/TLS設定の引き継ぎ
    |
    +-- Transferオブジェクト返却

Invoke-DbaDbTransfer
    |
    +-- New-DbaDbTransfer (InputObjectなし時)
    |
    +-- Register-ObjectEvent (DataTransferEvent)
    |
    +-- 転送実行
    |       +-- $transfer.ScriptTransfer() (ScriptOnly時)
    |       +-- $transfer.TransferData() (通常時)
    |
    +-- 結果オブジェクト出力
            +-- PSCustomObject
```

### データフロー図

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

SqlInstance      ------>  Get-DbaDatabase
Database                       |
                              v
                   Transfer オブジェクト作成
                              |
CopyAllObjects/  ------>  コピー対象設定
CopyAll                       |
                              v
DestinationSql   ------>  宛先接続設定
Instance                 (SSL/TLS引き継ぎ)
                              |
SchemaOnly/      ------>  転送モード設定
DataOnly                      |
                              v
                   Invoke-DbaDbTransfer
                              |
ScriptOnly       ------>  ScriptTransfer()  ----->  T-SQL スクリプト
                              |
                              v
                   TransferData()  ----->  PSCustomObject
                                           (SourceInstance,
                                            DestinationInstance,
                                            Status, Elapsed, Log)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbTransfer.ps1 | `public/Invoke-DbaDbTransfer.ps1` | ソース | 転送実行コマンド |
| New-DbaDbTransfer.ps1 | `public/New-DbaDbTransfer.ps1` | ソース | 転送オブジェクト作成コマンド |
| New-DbaScriptingOption.ps1 | `public/New-DbaScriptingOption.ps1` | ソース | スクリプトオプション作成 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
