# 機能設計書 531-New-DbaSsisCatalog

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるNew-DbaSsisCatalog機能の設計仕様を定義するものである。この機能はSQL Server 2012以降のインスタンスにSSIS Catalog (SSISDB)データベースを作成・有効化する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server Integration Services (SSIS)パッケージをサーバー上でデプロイ・管理・実行するためには、SSIS Catalogデータベース(SSISDB)が必要である。SQL ServerをSSISと共にインストールしても、このカタログは自動作成されず、CLR統合の有効化と暗号化用マスターキーのパスワード設定を含む別途のセットアップ作業が必要となる。本機能は、この複雑なセットアップをコマンドひとつで自動化し、管理者の作業負荷を軽減する。

**機能の利用シーン**：
- 新規SQL ServerインスタンスのSSIS環境構築時
- 災害復旧後のSSIS環境再構築
- 開発・テスト環境のSSIS環境一括セットアップ
- インフラ自動化パイプラインでのSSIS環境プロビジョニング

**主要な処理内容**：
1. PowerShell Core (Linux/macOS)での実行可否チェック（Windows専用機能）
2. SecurePasswordまたはCredentialパラメータの検証
3. 対象SQL Serverインスタンスへの接続（最小バージョン SQL Server 2005）
4. SSISサービスの稼働状態確認（Get-DbaServiceまたはGet-Service使用）
5. CLR統合（IsSqlClrEnabled）の有効化状態確認
6. IntegrationServicesオブジェクト経由での既存カタログ存在確認
7. 新規SSIS Catalogの作成とパスワード設定

**関連システム・外部連携**：
- SQL Server Management Objects (SMO) - IntegrationServices名前空間
- SQL Serverサービス（SSIS）- MsDtsServerサービス
- Windows PowerShell Remoting（リモートサービス確認時）

**権限による制御**：
- SQL Serverのsysadmin権限が必要
- SSISサービス状態確認のためのサーバーへのアクセス権限
- CLR統合設定確認・変更のための権限

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコマンド実行 |

## 機能種別

データ作成処理（CREATE）/ 環境構築

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス。パイプライン入力可能 | 有効なSQL Server接続文字列であること |
| SqlCredential | PSCredential | No | SQL Server接続用の代替認証情報 | 有効なPSCredentialオブジェクト |
| Credential | PSCredential | No | マスターキーパスワードを含むPSCredential（パスワード部分のみ使用） | SecurePasswordと排他（どちらか必須） |
| SecurePassword | Security.SecureString | No | SSIS Catalogマスターキーの暗号化パスワード | Credentialと排他（どちらか必須） |
| SsisCatalog | string | No | 作成するSSISカタログ名。デフォルト: SSISDB | 有効なSQL Server識別子 |
| EnableException | switch | No | 例外を呼び出し元にスローするかどうか | - |

### 入力データソース

- パラメータ入力（コマンドライン引数、パイプライン）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾SQL Serverインスタンス名（computer\instance形式） |
| SsisCatalog | string | 作成されたSSIS Catalogデータベース名 |
| Created | boolean | カタログ作成成功フラグ（常にtrue） |

### 出力先

- 標準出力（PSCustomObject）
- パイプライン出力

## 処理フロー

### 処理シーケンス

```
1. 環境チェック（beginブロック）
   ├─ PowerShell Coreチェック（Linux/macOS不可）
   └─ パスワードパラメータ検証（SecurePasswordまたはCredential必須）

2. インスタンス処理ループ（processブロック）
   ├─ SQL Server接続確立（Connect-DbaInstance、最小バージョン10）
   ├─ SSISサービス稼働確認
   │   ├─ Get-DbaService試行
   │   └─ Get-Service/Invoke-Command2フォールバック
   ├─ CLR統合有効化確認（Get-DbaSpConfigure）
   ├─ IntegrationServicesオブジェクト生成
   ├─ 既存カタログ存在確認
   └─ SSIS Catalog作成
       ├─ Catalogオブジェクト生成（パスワード設定）
       └─ Create()メソッド実行
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{PowerShell Core?}
    B -->|Yes| C[エラー: 非サポート]
    B -->|No| D{パスワード指定あり?}
    D -->|No| E[エラー: パスワード必須]
    D -->|Yes| F[foreach SqlInstance]
    F --> G[Connect-DbaInstance]
    G --> H{SSISサービス稼働中?}
    H -->|No| I[エラー: SSIS未稼働]
    H -->|Yes| J{CLR統合有効?}
    J -->|No| K[エラー: CLR無効]
    J -->|Yes| L[IntegrationServices生成]
    L --> M{カタログ存在?}
    M -->|Yes| N[エラー: 既存カタログ]
    M -->|No| O[Catalog作成]
    O --> P[PSCustomObject出力]
    P --> Q{次のインスタンス?}
    Q -->|Yes| F
    Q -->|No| R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Windows専用 | Linux/macOSでは実行不可 | PowerShell Core環境 |
| BR-002 | パスワード必須 | SecurePasswordまたはCredentialのいずれかが必須 | 常時 |
| BR-003 | SSIS稼働確認 | SSISサービスが稼働中であること | 常時 |
| BR-004 | CLR有効化 | IsSqlClrEnabledが有効であること | 常時 |
| BR-005 | カタログ重複禁止 | 既存SSISカタログがある場合は作成不可 | 常時 |
| BR-006 | 最小バージョン | SQL Server 2005（バージョン10）以上が必要 | 常時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| SSIS Catalog作成 | SSISDB（データベース全体） | CREATE DATABASE | SSISカタログデータベースの作成 |

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

#### SSISDB (SSIS Catalog Database)

SMO IntegrationServicesオブジェクト経由でCatalog.Create()メソッドを使用して作成。内部的にはSSISDBデータベースの作成、必要なスキーマ・テーブル・ストアドプロシージャの構築が行われる。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 非サポート環境 | PowerShell Core (Linux/macOS) | Windows環境で実行する |
| - | パラメータ不足 | SecurePassword/Credential両方なし | どちらかのパラメータを指定 |
| ConnectionError | 接続エラー | SQL Server接続失敗 | 接続情報・ネットワークを確認 |
| - | サービス未稼働 | SSISサービス停止中 | SSISサービスを開始する |
| - | CLR無効 | CLR統合が無効 | Set-DbaSpConfigureでCLR有効化 |
| - | カタログ存在 | SSISカタログ既存 | 既存カタログを確認・削除 |

### リトライ仕様

明示的なリトライ処理は実装されていない。Stop-Function -Continueにより、複数インスタンス処理時にエラーが発生しても次のインスタンス処理を継続する。

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

SMO IntegrationServices.Catalog.Create()メソッドが内部的にトランザクションを管理する。途中でエラーが発生した場合はロールバックされる。

## パフォーマンス要件

- SSIS Catalog作成は数秒から数十秒かかる場合がある
- ネットワーク経由でのサービス確認には追加の遅延が発生する可能性

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

- マスターキーパスワードはSecureString型で取り扱い、メモリ上で平文として保持する時間を最小化
- SecureStringToBSTRとPtrToStringAutoを使用して一時的に復号化
- SQL Server認証情報はPSCredentialオブジェクトとして安全に取り扱い
- sysadmin権限が必要なため、実行ユーザーの権限を事前に確認

## 備考

- SSIS CatalogはSSISパッケージのデプロイ・実行・監視に必須のコンポーネント
- 一度作成したSSISDBのパスワードは変更可能だが、既存の暗号化データに影響する
- 標準名「SSISDB」以外の名前を使用する場合、一部のツールで互換性問題が発生する可能性

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaSsisCatalog.ps1 | `public/New-DbaSsisCatalog.ps1` | 出力オブジェクト構造（163-169行目）を確認 |

**読解のコツ**: PSCustomObjectで定義される出力プロパティを確認し、何が返却されるか把握する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaSsisCatalog.ps1 | `public/New-DbaSsisCatalog.ps1` | param()ブロック（78-87行目）でパラメータ定義を確認 |

**主要処理フロー**:
1. **88-100行目**: beginブロックで環境チェックとパスワード検証
2. **101-104行目**: processブロック開始とFunctionInterruptチェック
3. **105-110行目**: SQL Server接続確立
4. **112-136行目**: SSISサービス稼働確認（Get-DbaService + Get-Service fallback）
5. **139-143行目**: CLR統合有効化確認
6. **145-150行目**: IntegrationServicesオブジェクト生成
7. **152-178行目**: カタログ存在確認と作成処理

#### Step 3: 関連機能を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaService.ps1 | `public/Get-DbaService.ps1` | サービス情報取得の仕組み |
| 3-2 | Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | sp_configure設定取得方法 |
| 3-3 | Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | SQL Server接続の共通処理 |

**主要処理フロー**:
- **114行目**: Get-DbaServiceによるサービス情報取得
- **139行目**: Get-DbaSpConfigureによるCLR設定確認
- **107行目**: Connect-DbaInstanceによるSMO接続確立

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

```
New-DbaSsisCatalog
    │
    ├─ Test-FunctionInterrupt（関数中断チェック）
    │
    ├─ Connect-DbaInstance（SQL Server接続）
    │      └─ 最小バージョン10を指定
    │
    ├─ Get-DbaService（SSISサービス確認）
    │      └─ Invoke-Command2（リモート実行fallback）
    │
    ├─ Get-DbaSpConfigure（CLR設定確認）
    │
    ├─ Microsoft.SqlServer.Management.IntegrationServices.IntegrationServices
    │      └─ SMOオブジェクト生成
    │
    └─ Microsoft.SqlServer.Management.IntegrationServices.Catalog
           └─ Create()メソッドでカタログ作成
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance ───────▶ SMO Server Object
                              │
SecurePassword ──────────────┤
or Credential                │
                              │
                              ▼
                       Get-DbaService ──────────▶ サービス稼働確認
                              │
                              ▼
                       Get-DbaSpConfigure ──────▶ CLR設定確認
                              │
                              ▼
                       IntegrationServices ─────▶ カタログ確認
                              │
                              ▼
                       Catalog.Create() ────────▶ PSCustomObject
                                                  (ComputerName,
                                                   InstanceName,
                                                   SqlInstance,
                                                   SsisCatalog,
                                                   Created)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaSsisCatalog.ps1 | `public/New-DbaSsisCatalog.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続共通関数 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SQL Serverサービス取得 |
| Get-DbaSpConfigure.ps1 | `public/Get-DbaSpConfigure.ps1` | ソース | sp_configure設定取得 |
| Invoke-Command2.ps1 | `private/Invoke-Command2.ps1` | ソース | リモートコマンド実行ラッパー |
