# 画面設計書 81-アーティクル管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるレプリケーションアーティクル管理機能の設計仕様を定義する。アーティクルとは、SQLレプリケーションにおいてパブリッシャーからサブスクライバーへ複製されるテーブル、ビュー、またはストアドプロシージャを定義するオブジェクトである。

### 本画面の処理概要

本機能は、SQL Serverレプリケーショントポロジにおけるアーティクル（複製対象オブジェクト）の管理を行うコマンドラインインターフェースを提供する。

**業務上の目的・背景**：SQL Serverのレプリケーション機能を使用してデータを分散させる環境において、どのテーブルやビューがレプリケーションに含まれているかを管理・監査することは重要な運用タスクである。本機能は、SSMSを使用せずにPowerShellからアーティクルの追加・取得・削除・列情報取得を一括で行うことを可能にし、レプリケーション構成の自動化と監視を支援する。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaReplArticle` - アーティクル情報の取得
- `Add-DbaReplArticle` - アーティクルの追加
- `Remove-DbaReplArticle` - アーティクルの削除
- `Get-DbaReplArticleColumn` - アーティクル列情報の取得
- `New-DbaReplCreationScriptOptions` - 作成スクリプトオプションの生成

**主要な操作・処理内容**：
1. レプリケーションパブリケーション内のアーティクル一覧を取得し、各アーティクルの名前、タイプ、ソースオブジェクト情報を表示
2. 既存のパブリケーションに新しいテーブルやビューをアーティクルとして追加
3. パブリケーションからアーティクルを削除（サブスクリプションがある場合は自動的に先に削除）
4. 垂直パーティショニング（列フィルタリング）の設定確認のためのアーティクル列情報取得
5. アーティクル作成時のスキーマオプション（インデックス、制約等）をカスタマイズ

**画面遷移**：
- 入力元：`Get-DbaReplPublication`でパブリケーション情報を取得後、パイプラインで連携
- 出力先：アーティクルオブジェクトは`Remove-DbaReplArticle`にパイプライン入力可能

**権限による表示制御**：sysadmin権限またはdb_owner権限が必要。レプリケーションの設定変更にはdistributor_admin権限も必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 443 | Get-DbaReplArticle | 主機能 | アーティクルの取得 |
| 437 | Add-DbaReplArticle | 主機能 | アーティクルの追加 |
| 454 | Remove-DbaReplArticle | 主機能 | アーティクルの削除 |
| 444 | Get-DbaReplArticleColumn | 補助機能 | アーティクル列の取得 |
| 451 | New-DbaReplCreationScriptOptions | 補助機能 | 作成スクリプトオプションの作成 |
| 446 | Get-DbaReplPublication | 遷移元機能 | パブリケーション情報の取得 |

## 画面種別

コマンドラインインターフェース（CLI） / 一覧・詳細・登録・削除

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Get-DbaReplArticle -SqlInstance <インスタンス名>`
- `Add-DbaReplArticle -SqlInstance <インスタンス名> -Database <DB名> -Publication <パブリケーション名> -Name <テーブル名>`
- `Remove-DbaReplArticle -SqlInstance <インスタンス名> -Database <DB名> -Publication <パブリケーション名> -Name <アーティクル名>`
- `Get-DbaReplArticleColumn -SqlInstance <インスタンス名>`

## 入出力項目

### Get-DbaReplArticle 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | いいえ | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| Database | object[] | いいえ | 対象データベース |
| Publication | object[] | いいえ | 対象パブリケーション |
| Schema | string[] | いいえ | スキーマフィルター |
| Name | string[] | いいえ | アーティクル名フィルター |
| EnableException | switch | いいえ | 例外処理の有効化 |

### Add-DbaReplArticle 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| Database | string | はい | 対象データベース |
| Publication | string | はい | 対象パブリケーション |
| Schema | string | いいえ | スキーマ（デフォルト: dbo） |
| Name | string | はい | 追加するオブジェクト名 |
| Filter | string | いいえ | 水平フィルタリング条件 |
| CreationScriptOptions | PSObject | いいえ | スキーマオプション |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

### Get-DbaReplArticle 出力オブジェクト

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| DatabaseName | string | データベース名 |
| PublicationName | string | パブリケーション名 |
| Name | string | アーティクル名 |
| Type | string | アーティクルタイプ（Table/View/StoredProcedure） |
| VerticalPartition | bool | 垂直パーティショニングの有無 |
| SourceObjectOwner | string | ソースオブジェクトのスキーマ |
| SourceObjectName | string | ソースオブジェクト名 |

## イベント仕様

### 1-アーティクル取得（Get-DbaReplArticle）

1. SQLインスタンスに接続（Connect-DbaInstance）
2. アクセス可能なデータベース一覧を取得
3. 各データベースのパブリケーションを取得（Get-DbaReplPublication）
4. 各パブリケーションのArticlesプロパティからアーティクルを抽出
5. Schema/Name指定時はフィルタリング
6. 結果をパイプラインに出力

### 2-アーティクル追加（Add-DbaReplArticle）

1. レプリケーションサーバーオブジェクトを取得
2. パブリケーションの存在確認
3. パブリケーションタイプに応じてTransArticleまたはMergeArticleオブジェクトを作成
4. スキーマオプション、フィルター条件を設定
5. Create()メソッドでアーティクルを作成
6. トランザクション/スナップショットの場合はRefreshSubscriptions()を実行
7. 作成したアーティクルを返却

### 3-アーティクル削除（Remove-DbaReplArticle）

1. パブリケーション情報を取得
2. サブスクリプションが存在する場合はsp_dropsubscriptionで先に削除
3. アーティクルのRemove()メソッドを実行
4. 削除結果をオブジェクトで返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Add-DbaReplArticle | sysarticles | INSERT | アーティクルメタデータの追加 |
| Add-DbaReplArticle | sysarticlecolumns | INSERT | アーティクル列情報の追加 |
| Remove-DbaReplArticle | MSsubscriptions | DELETE | サブスクリプション情報の削除 |
| Remove-DbaReplArticle | sysarticles | DELETE | アーティクルメタデータの削除 |
| Get-DbaReplArticle | sysarticles | SELECT | アーティクル情報の取得 |

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

#### sysarticles（パブリケーションデータベース）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | -Nameパラメータ値 | アーティクル名 |
| INSERT | objid | ソーステーブルのobject_id | 自動取得 |
| INSERT | pubid | パブリケーションID | 自動取得 |
| INSERT | type | LogBased(1) or TableBased | レプリケーションタイプ依存 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 成功 | Article already exists in {Publication} on {instance} | 既存アーティクル追加試行時 |
| MSG002 | エラー | Publication {Publication} does not exist on {instance} | パブリケーション未存在時 |
| MSG003 | エラー | Filter should not include the word 'WHERE' | フィルター条件にWHERE含む |
| MSG004 | 成功 | Removed | アーティクル削除成功 |
| MSG005 | エラー | Article doesn't exist in {PublicationName} on {instance} | 削除対象アーティクル未存在時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionでエラーメッセージを表示し、次のインスタンスに継続 |
| パブリケーション未存在 | 警告メッセージを表示し処理をスキップ |
| アーティクル既存 | 既存通知を表示し処理をスキップ |
| 削除失敗 | エラーメッセージとIsRemoved=falseを返却 |
| CreationScriptOptionsの型不正 | エラーメッセージを表示し処理をスキップ |

## 備考

- レプリケーションライブラリ（Microsoft.SqlServer.Replication）のロードが必要
- アーティクル削除後は新しいスナップショットの生成が必要
- 垂直パーティショニング有効時は列単位でのレプリケーション制御が可能

---

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

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

### 推奨読解順序

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

レプリケーションアーティクルはMicrosoft.SqlServer.Replication.Articleオブジェクトとして表現される。

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

**読解のコツ**: .OUTPUTSセクションでMicrosoft.SqlServer.Replication.Articleの既定表示プロパティと追加プロパティを確認する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaReplArticle.ps1 | `public/Get-DbaReplArticle.ps1` | param()ブロック（107-116行目）で入力パラメータを確認 |

**主要処理フロー**:
1. **117-119行目**: Add-ReplicationLibraryでレプリケーションDLLをロード
2. **123-128行目**: Connect-DbaInstanceでサーバー接続
3. **140-147行目**: Get-DbaReplPublicationでパブリケーション取得
4. **149-156行目**: Schema/Nameでフィルタリング
5. **158-164行目**: NotePropertyを追加して出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Add-DbaReplArticle.ps1 | `public/Add-DbaReplArticle.ps1` | TransArticle/MergeArticleの分岐（184-190行目） |

**主要処理フロー**:
- **182-190行目**: パブリケーションタイプに応じたアーティクルオブジェクト生成
- **192-197行目**: アーティクルプロパティの設定
- **204-214行目**: スキーマオプションとフィルターの設定
- **216-226行目**: Create()とRefreshSubscriptions()の実行

#### Step 4: アーティクル削除処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaReplArticle.ps1 | `public/Remove-DbaReplArticle.ps1` | サブスクリプション削除とアーティクル削除の順序（148-156行目） |

**主要処理フロー**:
- **150-154行目**: sp_dropsubscriptionでサブスクリプションを先に削除
- **155-159行目**: Remove()メソッドでアーティクル削除

#### Step 5: スキーマオプションを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | New-DbaReplCreationScriptOptions.ps1 | `public/New-DbaReplCreationScriptOptions.ps1` | デフォルトオプションの設定（97-99行目） |

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

```
Get-DbaReplArticle
    │
    ├─ Add-ReplicationLibrary (内部関数)
    │      └─ レプリケーションDLLのロード
    │
    ├─ Connect-DbaInstance
    │      └─ SMOサーバーオブジェクト取得
    │
    └─ Get-DbaReplPublication
           └─ パブリケーション.Articlesプロパティ取得

Add-DbaReplArticle
    │
    ├─ Get-DbaReplServer
    │      └─ レプリケーションサーバーオブジェクト
    │
    ├─ Get-DbaReplPublication
    │      └─ パブリケーション存在確認
    │
    ├─ TransArticle.Create() / MergeArticle.Create()
    │      └─ sysarticlesへのINSERT
    │
    └─ Get-DbaReplArticle
           └─ 作成結果の返却

Remove-DbaReplArticle
    │
    ├─ Get-DbaReplArticle
    │      └─ 削除対象の取得
    │
    ├─ Get-DbaReplPublication
    │      └─ サブスクリプション確認
    │
    ├─ Invoke-DbaQuery (sp_dropsubscription)
    │      └─ サブスクリプション削除
    │
    └─ Article.Remove()
           └─ アーティクル削除
```

### データフロー図

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

SqlInstance ─────▶ Connect-DbaInstance ─────▶ SMO Server Object
                          │
Database/Publication ────▶│
                          ▼
                   Get-DbaReplPublication
                          │
                          ▼
                   Publications.Articles ─────▶ Article Object[]
                          │
Schema/Name ─────────────▶│ (フィルタリング)
                          ▼
                   Select-DefaultView ─────────▶ 画面出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaReplArticle.ps1 | `public/Get-DbaReplArticle.ps1` | ソース | アーティクル情報取得 |
| Add-DbaReplArticle.ps1 | `public/Add-DbaReplArticle.ps1` | ソース | アーティクル追加 |
| Remove-DbaReplArticle.ps1 | `public/Remove-DbaReplArticle.ps1` | ソース | アーティクル削除 |
| Get-DbaReplArticleColumn.ps1 | `public/Get-DbaReplArticleColumn.ps1` | ソース | アーティクル列情報取得 |
| New-DbaReplCreationScriptOptions.ps1 | `public/New-DbaReplCreationScriptOptions.ps1` | ソース | スキーマオプション生成 |
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | 依存 | パブリケーション情報取得 |
| Get-DbaReplServer.ps1 | `public/Get-DbaReplServer.ps1` | 依存 | レプリケーションサーバー取得 |
