# 機能設計書 437-Add-DbaReplArticle

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるAdd-DbaReplArticle機能の設計仕様を定義する。

### 本機能の処理概要

Add-DbaReplArticleは、既存のレプリケーションパブリケーションにテーブルまたはその他のデータベースオブジェクトをアーティクルとして追加する機能である。

**業務上の目的・背景**：SQL Serverレプリケーションでは、パブリケーションに含めるデータベースオブジェクトをアーティクルとして定義する必要がある。この機能は、SSMSを使用せずにコマンドラインからアーティクルを追加することで、レプリケーション構成の自動化と一貫性を実現する。新しいテーブルのレプリケーション追加や、水平フィルタリングの設定を効率化する。

**機能の利用シーン**：
- 新規テーブルをレプリケーション対象に追加する場合
- 水平フィルタリング（WHERE句）を適用したレプリケーション設定
- スキーマオプション（インデックス、統計等）のカスタマイズ
- レプリケーション構成の自動デプロイメント

**主要な処理内容**：
1. パブリケーションの存在確認
2. パブリケーションタイプに応じたアーティクルオブジェクト作成
3. スキーマオプション（CreationScriptOptions）の適用
4. 水平フィルター（Filter）の設定
5. SMOのCreateメソッドでアーティクル作成
6. トランザクション/スナップショットの場合はサブスクリプション更新

**関連システム・外部連携**：SQL Server Replication、パブリッシャー、サブスクライバー

**権限による制御**：パブリケーションデータベースに対するdb_owner権限またはsysadmin権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | 該当なし（コマンドライン機能） | - | - |

## 機能種別

データ操作 / INSERT処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | パブリケーションのSQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | 代替認証情報 | - |
| Database | string | Yes | パブリケーションが存在するデータベース | - |
| Publication | string | Yes | 対象パブリケーション名 | 存在確認 |
| Schema | string | No | オブジェクトのスキーマ名 | デフォルトはdbo |
| Name | string | Yes | アーティクルとして追加するオブジェクト名 | - |
| Filter | string | No | 水平フィルタリング用WHERE句 | WHEREキーワード不可 |
| CreationScriptOptions | PSObject | No | スキーマ要素の作成オプション | CreationScriptOptions型 |
| WhatIf | switch | No | 実行前確認（実行しない） | - |
| Confirm | switch | No | 実行確認プロンプト | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SqlInstanceの直接指定（パイプライン可）
- パブリケーションは既存のものを参照

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| DatabaseName | string | アーティクルを含むデータベース名 |
| PublicationName | string | アーティクルを含むパブリケーション名 |
| Name | string | アーティクル名 |
| Type | string | アーティクルタイプ（table等） |
| VerticalPartition | bool | 垂直パーティション（列フィルタ）使用有無 |
| SourceObjectOwner | string | ソースオブジェクトのスキーマ |
| SourceObjectName | string | ソースオブジェクト名 |

### 出力先

- 作成されたアーティクルオブジェクトをパイプライン出力

## 処理フロー

### 処理シーケンス

```
1. 入力検証
   └─ CreationScriptOptionsの型確認
   └─ FilterにWHEREキーワードがないことを確認
2. レプリケーションサーバー接続
   └─ Get-DbaReplServerで接続
3. パブリケーション取得
   └─ Get-DbaReplPublicationで対象パブリケーション取得
4. アーティクルオブジェクト作成
   └─ Transactional/Snapshot: TransArticle
   └─ Merge: MergeArticle
5. プロパティ設定
   └─ Name、DatabaseName、SourceObjectName等を設定
6. オプション適用
   └─ CreationScriptOptions指定時はSchemaOptionに設定
   └─ Filter指定時はFilterClauseに設定
7. アーティクル作成
   └─ IsExistingObjectで存在確認後、Createメソッド実行
8. サブスクリプション更新
   └─ Transactional/SnapshotではRefreshSubscriptions実行
9. 結果返却
   └─ Get-DbaReplArticleで作成結果を取得
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{CreationScriptOptions型確認}
    B -->|不正| C[Stop-Function]
    B -->|OK| D{FilterにWHERE?}
    D -->|あり| E[Stop-Function]
    D -->|なし| F[Get-DbaReplServer]
    F --> G[Get-DbaReplPublication]
    G --> H{パブリケーション存在?}
    H -->|No| I[Stop-Function]
    H -->|Yes| J{パブリケーションタイプ?}
    J -->|Transactional/Snapshot| K[TransArticle作成]
    J -->|Merge| L[MergeArticle作成]
    K --> M[プロパティ設定]
    L --> M
    M --> N{CreationScriptOptions?}
    N -->|Yes| O[SchemaOption設定]
    N -->|No| P[次へ]
    O --> P
    P --> Q{Filter?}
    Q -->|Yes| R[FilterClause設定]
    Q -->|No| S[次へ]
    R --> S
    S --> T{IsExistingObject?}
    T -->|Yes| U[Stop-Function 既存]
    T -->|No| V[Create実行]
    V --> W{Transactional/Snapshot?}
    W -->|Yes| X[RefreshSubscriptions]
    W -->|No| Y[次へ]
    X --> Y
    Y --> Z[Get-DbaReplArticle]
    Z --> AA[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Filterキーワード制限 | Filter文字列にWHEREキーワードを含めてはならない | Filter指定時 |
| BR-002 | パブリケーション存在必須 | 対象パブリケーションが事前に存在する必要がある | 常時 |
| BR-003 | アーティクル重複不可 | 同一パブリケーションに同名アーティクルは追加不可 | 常時 |
| BR-004 | タイプ自動設定 | パブリケーションタイプに応じてアーティクルタイプが自動設定 | 常時 |
| BR-005 | サブスクリプション更新 | トランザクション/スナップショットではサブスクリプション自動更新 | Transactional/Snapshot |

### 計算ロジック

アーティクルタイプ設定：
- Transactional/Snapshot: ArticleOptions::LogBased
- Merge: ArticleOptions::TableBased

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| アーティクル追加 | distribution.dbo.MSpublisher_databases | INSERT | アーティクルメタデータ追加 |
| サブスクリプション更新 | 配布データベース | UPDATE | サブスクリプション情報更新 |

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

RMO（Replication Management Objects）を介した間接的な操作のため、直接のテーブル操作仕様は非公開。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 型エラー | CreationScriptOptionsが不正な型 | New-DbaReplCreationScriptOptionsで作成 |
| - | フィルタエラー | FilterにWHEREキーワードを含む | WHEREキーワードを削除 |
| - | パブリケーション不存在 | 指定パブリケーションが存在しない | パブリケーション名を確認 |
| - | 重複エラー | アーティクルが既に存在 | 既存アーティクルを削除するか別名を使用 |

### リトライ仕様

リトライ機能は実装されていない。

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

トランザクション管理はRMOに委譲。

## パフォーマンス要件

特定のパフォーマンス要件は定義されていない。大規模テーブルの追加時はスナップショット生成に時間がかかる可能性。

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

- パブリケーションデータベースへの適切な権限（db_owner、sysadmin）が必要
- SqlCredentialパラメータでMFA以外の認証方式をサポート

## 備考

- CreationScriptOptionsはNew-DbaReplCreationScriptOptionsで作成
- トランザクションレプリケーションではアーティクル追加後に自動でサブスクリプション更新

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Replication.TransArticle | (RMO) | トランザクションアーティクルクラス |
| 1-2 | Microsoft.SqlServer.Replication.MergeArticle | (RMO) | マージアーティクルクラス |

**読解のコツ**: TransArticleとMergeArticleは異なるクラスだが、基本的なプロパティ（Name、DatabaseName等）は共通。Typeプロパティの設定値が異なる。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Add-DbaReplArticle.ps1 | `public/Add-DbaReplArticle.ps1` | パラメータ定義、バリデーション |

**主要処理フロー**:
1. **132-147行目**: パラメータ定義
2. **150-157行目**: 入力検証（CreationScriptOptions型、Filter内容）

#### Step 3: アーティクル作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Add-DbaReplArticle.ps1 | `public/Add-DbaReplArticle.ps1` | アーティクル作成のコアロジック |

**主要処理フロー**:
- **159-164行目**: Get-DbaReplServerで接続
- **167-177行目**: パブリケーション取得・確認
- **179-201行目**: アーティクルオブジェクト作成・プロパティ設定
- **203-230行目**: オプション適用、Create実行、結果取得

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

```
Add-DbaReplArticle
    │
    ├─ Get-DbaReplServer
    │      └─ レプリケーションサーバー接続
    │
    ├─ Get-DbaReplPublication
    │      └─ パブリケーション取得
    │
    ├─ New-Object TransArticle/MergeArticle
    │      └─ アーティクルオブジェクト作成
    │
    ├─ [Article].Create()
    │      └─ アーティクル登録
    │
    ├─ [Publication].RefreshSubscriptions()
    │      └─ サブスクリプション更新
    │
    └─ Get-DbaReplArticle
           └─ 作成結果取得
```

### データフロー図

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

SqlInstance ────────────▶ Get-DbaReplServer ─────────┐
                                                     │
Database + Publication ─▶ Get-DbaReplPublication ───┤
                                                     │
Name + Schema ──────────▶ New-Object Article ────────┤
                                                     │
Filter ─────────────────▶ FilterClause設定 ──────────┤
                                                     │
CreationScriptOptions ──▶ SchemaOption設定 ──────────┼──▶ Article
                                                     │
                         Create() ───────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Add-DbaReplArticle.ps1 | `public/Add-DbaReplArticle.ps1` | ソース | メイン機能実装 |
| Get-DbaReplServer.ps1 | `public/Get-DbaReplServer.ps1` | ソース | レプリケーションサーバー取得 |
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | ソース | パブリケーション取得 |
| Get-DbaReplArticle.ps1 | `public/Get-DbaReplArticle.ps1` | ソース | アーティクル取得 |
| New-DbaReplCreationScriptOptions.ps1 | `public/New-DbaReplCreationScriptOptions.ps1` | ソース | スキーマオプション作成 |
