# 機能設計書 529-Copy-DbaSsisCatalog

## 概要

本ドキュメントは、SSIS カタログをインスタンス間で移行する `Copy-DbaSsisCatalog` コマンドの機能設計書です。

### 本機能の処理概要

SQL Server Integration Services (SSIS) の SSISDB カタログ（フォルダー、プロジェクト、環境）をソースインスタンスから宛先インスタンスへ移行する PowerShell コマンドです。サーバー移行、環境プロモーション、障害復旧シナリオで使用されます。

**業務上の目的・背景**：SSIS プロジェクトとその関連環境設定を複数のサーバー間で一貫して管理することは、エンタープライズデータ統合において重要です。開発環境から本番環境への昇格、サーバー移行、障害復旧など、様々なシナリオで SSIS カタログの複製が必要になります。本コマンドは、SSISDB カタログ構造全体を効率的にコピーし、手動での複雑なデプロイメント作業を自動化します。

**機能の利用シーン**：
- 開発環境から本番環境への SSIS プロジェクト昇格
- サーバー移行時の SSISDB カタログ複製
- 障害復旧のための SSIS 環境バックアップ
- 複数環境間での設定同期
- CI/CD パイプラインでの自動デプロイメント

**主要な処理内容**：
1. ソースとデスティネーションへの接続確立
2. Integration Services サービスの確認
3. SSISDB カタログの存在確認（必要に応じて作成）
4. フォルダーの作成/更新
5. プロジェクトのデプロイメント
6. 環境の複製

**関連システム・外部連携**：SQL Server Integration Services、SSISDB データベース、SMO Integration Services 名前空間

**権限による制御**：sysadmin 権限が必要です。SSISDB カタログの作成には CLR 統合の有効化が必要な場合があります。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - Integration Services Catalogs | 参照画面 | SSISDB カタログの管理と同等 |

## 機能種別

移行 / データ連携

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソース SQL Server インスタンス | SQL Server 2012 以上 |
| Destination | DbaInstanceParameter[] | Yes | デスティネーション SQL Server インスタンス | SQL Server 2012 以上 |
| SourceSqlCredential | PSCredential | No | ソース接続用の代替認証情報 | - |
| DestinationSqlCredential | PSCredential | No | デスティネーション接続用の代替認証情報 | - |
| Project | string | No | コピーするプロジェクト名（単一） | - |
| Folder | string | No | コピーするフォルダー名（単一） | - |
| Environment | string | No | コピーする環境名（単一） | - |
| CreateCatalogPassword | SecureString | No | 新規カタログ作成時のパスワード | - |
| EnableSqlClr | switch | No | 自動的に CLR を有効化 | - |
| Force | switch | No | 既存オブジェクトを上書き | - |
| EnableException | switch | No | 例外をスローする | - |

### 入力データソース

- ソースインスタンスの SSISDB カタログ
- Microsoft.SqlServer.Management.IntegrationServices 名前空間

## 出力仕様

### 出力データ

本コマンドは移行操作を実行し、出力オブジェクトを返しません。Verbose ストリームで操作の詳細を確認できます。

### 出力先

- Verbose ストリーム（操作詳細）
- Warning ストリーム（警告メッセージ）

## 処理フロー

### 処理シーケンス

```
1. プラットフォームチェック
   └─ PowerShell Core（Linux/macOS）では実行不可
2. ソース接続の確立
   └─ Connect-DbaInstance（MinimumVersion 11）
   └─ IntegrationServices オブジェクト作成
   └─ SSISDB カタログ存在確認
3. 各デスティネーションの処理ループ
   └─ デスティネーション接続の確立
   └─ Integration Services サービス確認
   └─ IntegrationServices オブジェクト作成
4. SSISDB カタログ処理
   └─ カタログ存在確認
   └─ 存在しない場合
      └─ CLR 有効化確認・実行
      └─ カタログ作成（パスワード入力または指定）
5. フォルダー処理
   └─ -Folder 指定時: 指定フォルダーのみ
   └─ 指定なし: 全フォルダー
   └─ 新規フォルダー作成 or -Force で再作成
6. プロジェクト処理
   └─ -Project 指定時: 指定プロジェクトのみ
   └─ 指定なし: フォルダー内全プロジェクト
   └─ catalog.get_project でバイナリ取得
   └─ DeployProject でデプロイ
7. 環境処理
   └─ -Environment 指定時: 指定環境のみ
   └─ 指定なし: フォルダー内全環境
   └─ 環境変数のコピー（Sensitive 値含む）
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{PS Core?}
    B -->|Yes| C[エラー終了]
    B -->|No| D[ソース接続]
    D --> E{SSISDB存在?}
    E -->|No| F[エラー終了]
    E -->|Yes| G[各デスティネーションループ]
    G --> H[デスティネーション接続]
    H --> I{SSIS サービス?}
    I -->|No| J[警告・継続]
    I -->|Yes| K{SSISDB存在?}
    K -->|No| L{CLR有効?}
    L -->|No| M[CLR有効化確認]
    L -->|Yes| N[カタログ作成]
    M --> N
    K -->|Yes| O[フォルダー処理]
    N --> O
    O --> P{既存フォルダー?}
    P -->|Yes -Force| Q[再作成]
    P -->|Yes| R[スキップ]
    P -->|No| S[作成]
    Q --> T[プロジェクトデプロイ]
    S --> T
    T --> U[環境コピー]
    U --> V{次のデスティネーション?}
    V -->|Yes| G
    V -->|No| W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | プラットフォーム制限 | Linux/macOS では実行不可 | 常時 |
| BR-002 | 最小バージョン | SQL Server 2012 以上が必要 | 常時 |
| BR-003 | CLR 要件 | SSISDB には CLR 統合が必要 | カタログ作成時 |
| BR-004 | パスワード要件 | 新規カタログ作成時はパスワードが必要 | カタログ作成時 |
| BR-005 | 階層的コピー | -Folder 指定時はそのフォルダーのみ対象 | -Folder 指定時 |
| BR-006 | Force 動作 | 既存オブジェクトを削除して再作成 | -Force 指定時 |

### 計算ロジック

プロジェクトデプロイ:
- catalog.get_project ストアドプロシージャでバイナリ取得
- DeployProject メソッドでデプロイ

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| カタログ取得 | SSISDB.catalog | SELECT | カタログ情報取得 |
| フォルダー作成 | SSISDB.internal.folders | INSERT | フォルダー作成 |
| プロジェクト取得 | SSISDB.catalog.get_project | EXEC | プロジェクトバイナリ取得 |
| プロジェクトデプロイ | SSISDB.internal.projects | INSERT | プロジェクトデプロイ |
| 環境作成 | SSISDB.internal.environments | INSERT | 環境作成 |
| 変数作成 | SSISDB.internal.environment_variables | INSERT | 環境変数作成 |

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

#### SSISDB.catalog.get_project

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| EXEC | @folder_name, @project_name | フォルダー名とプロジェクト名 | バイナリデータを返す |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | プラットフォームエラー | PowerShell Core で実行 | Windows PowerShell を使用 |
| - | バージョンエラー | SQL Server 2012 未満 | SQL Server 2012 以上を使用 |
| - | カタログエラー | ソースに SSISDB がない | SSISDB カタログを作成 |
| - | サービスエラー | SSIS サービスが未インストール | SSIS をインストール |
| - | CLR エラー | CLR が無効 | CLR を有効化 |

### リトライ仕様

リトライなし（throw による即時エラー）

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

各オブジェクト（フォルダー、プロジェクト、環境）は個別にコミットされる

## パフォーマンス要件

- プロジェクトサイズに比例した処理時間
- 大規模プロジェクトではネットワーク転送時間を考慮

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

- sysadmin 権限が必要
- Sensitive 環境変数は暗号化されて転送
- カタログパスワードは SecureString で取り扱い

## 備考

- PowerShell Core では実行不可（Windows 専用）
- throw ステートメントが必要な設計（開発者注記）
- パスワード確認は対話的に行われる（自動化時は CreateCatalogPassword を使用）

---

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

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

### 推奨読解順序

#### Step 1: 内部関数を理解する

本関数には複数の内部関数が定義されています。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaSsisCatalog.ps1 | `public/Copy-DbaSsisCatalog.ps1` | 内部関数定義（128-275行目） |

**読解のコツ**:
- Get-RemoteIntegrationService: SSIS サービス確認
- Invoke-ProjectDeployment: プロジェクトデプロイ
- New-CatalogFolder: フォルダー作成
- New-FolderEnvironment: 環境作成
- New-SSISDBCatalog: カタログ作成

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

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

**主要処理フロー**:
1. **102-117行目**: パラメータ定義
2. **119-300行目**: begin ブロック（接続と内部関数）
3. **301-559行目**: process ブロック（移行処理）

#### Step 3: カタログ処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaSsisCatalog.ps1 | `public/Copy-DbaSsisCatalog.ps1` | カタログ処理 |

**主要処理フロー**:
- **324-391行目**: SSISDB カタログ確認と作成
- **392-447行目**: フォルダー処理
- **461-498行目**: プロジェクトデプロイ
- **500-558行目**: 環境コピー

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

```
Copy-DbaSsisCatalog
    │
    ├─ Connect-DbaInstance (Source)
    │      └─ SQL Server SMO 接続（MinimumVersion 11）
    │
    ├─ New-Object IntegrationServices
    │      └─ SSIS 管理オブジェクト作成
    │
    ├─ Get-RemoteIntegrationService
    │      └─ SSIS サービス確認
    │
    ├─ New-SSISDBCatalog
    │      └─ カタログ作成（必要時）
    │
    ├─ New-CatalogFolder
    │      └─ フォルダー作成
    │
    ├─ Invoke-ProjectDeployment
    │      ├─ catalog.get_project
    │      └─ DeployProject
    │
    └─ New-FolderEnvironment
           └─ 環境と変数の複製
```

### データフロー図

```
[ソース]             [処理]                    [デスティネーション]

SSISDB ────────▶ IntegrationServices ────▶ SSISDB
  │                      │
  ├─ Folders ───▶ New-CatalogFolder ────▶ Folders
  │                      │
  ├─ Projects ──▶ get_project ──────────▶ Projects
  │              DeployProject
  │                      │
  └─ Environments ▶ New-FolderEnvironment ▶ Environments
                   Variables.Add              Variables
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaSsisCatalog.ps1 | `public/Copy-DbaSsisCatalog.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SSIS サービス確認 |
