# 機能設計書 452-New-DbaReplPublication

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける`New-DbaReplPublication`関数の機能設計を定義する。この関数はSQL Serverインスタンス上にレプリケーションパブリケーションを作成し、トランザクション、スナップショット、またはマージレプリケーションの基盤を構築する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverレプリケーションは、データベース間でデータを配布するための重要な機能である。パブリケーションは、サブスクライバーに複製するデータの論理的なコンテナとして機能する。本関数は、パブリッシャー側のレプリケーション設定を自動化し、手動でのSSMS操作を不要にすることで、大規模環境でのレプリケーション構成を効率化する。

**機能の利用シーン**：
- 災害復旧用のレプリケーション環境構築時
- レポートサーバー向けのデータ配布設定時
- 複数拠点へのデータ同期構成時
- CI/CD パイプラインでのレプリケーション自動構成時

**主要な処理内容**：
1. 対象インスタンスがパブリッシャーとして構成されているか検証
2. 指定データベースのレプリケーション機能を有効化
3. レプリケーションタイプに応じたLog Reader Agent作成（Transactional/Snapshot）
4. パブリケーションオブジェクトの作成
5. Snapshot Agentジョブの作成

**関連システム・外部連携**：SQL Server Replication Management Objects (RMO)ライブラリ、SQL Server Agent（Log Reader Agent、Snapshot Agent）、ディストリビューター

**権限による制御**：sysadmin固定サーバーロール、または db_owner 固定データベースロールとレプリケーション管理者権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | SQL Server Management Studio - 新しいパブリケーションウィザード | 参照画面 | パブリケーション作成処理に相当 |
| N/A | SQL Server Management Studio - レプリケーションモニター | 結果表示画面 | 作成されたパブリケーションの監視 |

## 機能種別

CRUD操作（Create） / レプリケーション構成

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | パブリッシャーとなるSQL Serverインスタンス | パイプライン入力対応、接続可能性検証 |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 | 有効な認証情報 |
| Database | String | Yes | パブリケーションを作成するデータベース名 | 存在するデータベースであること |
| Name | String | Yes | パブリケーションの名前 | 一意の名前 |
| Type | String | Yes | レプリケーションタイプ（Snapshot/Transactional/Merge） | ValidateSet検証 |
| LogReaderAgentCredential | PSCredential | No | Log Reader Agentの実行資格情報 | Windows認証用アカウント |
| EnableException | Switch | No | 例外を有効化 | なし |

### 入力データソース

- パラメータ入力
- SQL Serverインスタンスのメタデータ（パブリッシャー構成状態）
- 対象データベースのプロパティ

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | SQL Serverホストのコンピュータ名 |
| InstanceName | String | SQL Serverインスタンス名 |
| SqlInstance | String | フルSQL Serverインスタンス名 |
| DatabaseName | String | パブリケーションが作成されたデータベース名 |
| Name | String | パブリケーション名 |
| Type | String | レプリケーションタイプ |
| Articles | Collection | パブリケーションに含まれるアーティクル |
| Subscriptions | Collection | パブリケーションへのサブスクリプション |

### 出力先

パイプライン出力。`Get-DbaReplPublication`の結果オブジェクトとして返却される。

## 処理フロー

### 処理シーケンス

```
1. パブリッシャー構成の検証
   └─ Get-DbaReplServerでインスタンスがパブリッシャーかチェック
2. ReplicationDatabaseオブジェクトの設定
   └─ データベース名を設定し、LoadPropertiesで存在確認
3. レプリケーションタイプ別の処理分岐
   ├─ Transactional/Snapshot
   │   ├─ EnabledTransPublishing = $true
   │   ├─ Log Reader Agentが存在しない場合は作成
   │   ├─ TransPublicationオブジェクト作成
   │   └─ Snapshot Agent作成
   └─ Merge
       ├─ EnabledMergePublishing = $true
       ├─ MergePublicationオブジェクト作成
       └─ Snapshot Agent作成
4. パブリケーション情報の取得と出力
   └─ Get-DbaReplPublicationで作成結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Get-DbaReplServer]
    B --> C{パブリッシャー?}
    C -->|No| D[エラー: Enable-DbaReplPublishing実行必要]
    C -->|Yes| E[ReplicationDatabase設定]
    E --> F{データベース存在?}
    F -->|No| G[エラー: データベース不存在]
    F -->|Yes| H{Type判定}
    H -->|Transactional/Snapshot| I[EnabledTransPublishing有効化]
    I --> J{Log Reader Agent存在?}
    J -->|No| K[CreateLogReaderAgent]
    J -->|Yes| L[TransPublication作成]
    K --> L
    L --> M[CreateSnapshotAgent]
    H -->|Merge| N[EnabledMergePublishing有効化]
    N --> O[MergePublication作成]
    O --> P[CreateSnapshotAgent]
    M --> Q[Get-DbaReplPublication]
    P --> Q
    Q --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パブリッシャー前提条件 | インスタンスは事前にパブリッシャーとして構成されている必要がある | 常時適用 |
| BR-002 | Log Reader Agent自動作成 | Transactional/Snapshotの場合、Log Reader Agentが存在しなければ自動作成 | Type = Transactional または Snapshot |
| BR-003 | Snapshot Agent自動作成 | 全てのパブリケーションタイプでSnapshot Agentを自動作成 | 常時適用 |
| BR-004 | sysadminデフォルト動作 | sysadminメンバーの場合、Agent資格情報未指定でSQL Server Agentアカウント使用 | sysadminロールの場合 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| パブリケーション作成 | MSreplication_objects | INSERT | パブリケーションメタデータの登録 |
| Log Reader Agent作成 | msdb.dbo.sysjobs | INSERT | SQL Agentジョブの作成 |
| Snapshot Agent作成 | msdb.dbo.sysjobs | INSERT | SQL Agentジョブの作成 |

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

#### MSreplication_objects (distribution database)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | publication_id | 自動生成 | パブリケーション識別子 |
| INSERT | publisher_db | Database パラメータ値 | パブリッシャーデータベース名 |
| INSERT | publication | Name パラメータ値 | パブリケーション名 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | ConnectionError | SQL Server接続失敗 | 接続パラメータ確認、ネットワーク確認 |
| N/A | パブリッシャー未構成 | IsPublisher = false | Enable-DbaReplPublishingを実行 |
| N/A | データベース不存在 | LoadProperties() = false | 正しいデータベース名を指定 |

### リトライ仕様

本関数にリトライ機能は実装されていない。エラー発生時はStop-Functionで処理を停止する。

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

RMOオブジェクトのCreate()メソッドは内部的にトランザクションを使用。エラー時は自動ロールバック。

## パフォーマンス要件

パブリケーション作成は数秒で完了。大規模データベースでのLog Reader Agent初期化には時間がかかる場合がある。

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

- sysadminまたはdb_owner権限が必要
- LogReaderAgentCredentialは安全に管理すること
- ドメインアカウントの使用を推奨
- 認証情報はSecureStringとして処理される

## 備考

- Snapshot Agent の資格情報設定（SnapshotGenerationAgentProcessSecurity）は現在未実装（TODO）
- SqlStandardLogin/SqlStandardPasswordでのSQL認証接続も未実装

---

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

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

### 推奨読解順序

#### Step 1: 関数構造とパラメータを理解する

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

**読解のコツ**: `[parameter(Mandatory, ValueFromPipeline)]`はパイプライン入力対応の必須パラメータを示す。`[ValidateSet()]`はパラメータ値の制限を定義。

#### Step 2: パブリッシャー検証ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaReplPublication.ps1 | `public/New-DbaReplPublication.ps1` | 120-130行目のパブリッシャー検証処理 |

**主要処理フロー**:
1. **122行目**: `Get-DbaReplServer`でレプリケーションサーバー情報取得
2. **124-125行目**: `IsPublisher`プロパティでパブリッシャー構成確認
3. **128-129行目**: 接続エラー時のStop-Function呼び出し

#### Step 3: レプリケーションタイプ別の処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaReplPublication.ps1 | `public/New-DbaReplPublication.ps1` | 145-220行目のTransactional/Merge分岐処理 |

**主要処理フロー**:
- **145-163行目**: Transactional/Snapshot処理（EnabledTransPublishing、Log Reader Agent作成）
- **165-169行目**: Merge処理（EnabledMergePublishing）
- **171-181行目**: TransPublication作成とSnapshot Agent作成
- **196-204行目**: MergePublication作成

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

```
New-DbaReplPublication
    │
    ├─ Get-DbaReplServer
    │      └─ Connect-DbaInstance
    │
    ├─ [RMO] ReplicationDatabase
    │      ├─ LoadProperties()
    │      ├─ EnabledTransPublishing
    │      ├─ EnabledMergePublishing
    │      ├─ CreateLogReaderAgent()
    │      └─ CommitPropertyChanges()
    │
    ├─ [RMO] TransPublication
    │      ├─ Create()
    │      └─ CreateSnapshotAgent()
    │
    ├─ [RMO] MergePublication
    │      ├─ Create()
    │      └─ CreateSnapshotAgent()
    │
    └─ Get-DbaReplPublication
```

### データフロー図

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

SqlInstance ─────────────▶ Get-DbaReplServer ─────────────────────▶ パブリッシャー検証
                                   │
Database ────────────────▶ ReplicationDatabase.LoadProperties() ──▶ DB存在確認
                                   │
Name/Type ───────────────▶ TransPublication/MergePublication ─────▶ パブリケーション作成
                                   │
LogReaderAgentCredential ▶ CreateLogReaderAgent() ────────────────▶ Log Reader Agent
                                   │
                           CreateSnapshotAgent() ─────────────────▶ Snapshot Agent
                                   │
                           Get-DbaReplPublication ────────────────▶ 結果オブジェクト
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaReplPublication.ps1 | `public/New-DbaReplPublication.ps1` | ソース | メイン関数定義 |
| Get-DbaReplServer.ps1 | `public/Get-DbaReplServer.ps1` | ソース | レプリケーションサーバー情報取得 |
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | ソース | パブリケーション情報取得 |
| Enable-DbaReplPublishing.ps1 | `public/Enable-DbaReplPublishing.ps1` | ソース | パブリッシャー構成の前提条件 |
