# 画面設計書 82-サブスクリプション管理

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるレプリケーションサブスクリプション管理機能の設計仕様を定義する。サブスクリプションとは、パブリッシャーからサブスクライバーへのデータ配信関係を定義するレプリケーション構成要素である。

### 本画面の処理概要

本機能は、SQL Serverレプリケーショントポロジにおけるサブスクリプション（購読設定）の管理を行うコマンドラインインターフェースを提供する。

**業務上の目的・背景**：SQL Serverレプリケーション環境において、どのサブスクライバーがどのパブリケーションからデータを受信しているかを管理することは、データ配信トポロジの維持に不可欠である。本機能は、災害復旧サイトへのデータ複製、レポートデータベースの構築、または複数拠点へのデータ分散といったシナリオで、サブスクリプションの作成・監視・削除をPowerShellから一元管理することを可能にする。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaReplSubscription` - サブスクリプション情報の取得
- `New-DbaReplSubscription` - サブスクリプションの作成
- `Remove-DbaReplSubscription` - サブスクリプションの削除

**主要な操作・処理内容**：
1. パブリッシャーに登録されているサブスクリプション一覧を取得し、サブスクライバー名、サブスクリプションDB、タイプ（Push/Pull）を表示
2. 新しいサブスクリプションを作成し、パブリッシャーとサブスクライバー間のデータ同期を確立
3. 既存のサブスクリプションを削除してレプリケーション関係を解除
4. Push/Pullサブスクリプションタイプによるフィルタリング
5. サブスクライバー名、サブスクリプションデータベースによるフィルタリング

**画面遷移**：
- 入力元：`Get-DbaReplPublication`でパブリケーション情報を取得後の参照
- 関連：サブスクリプション作成前に`Get-DbaReplArticle`でアーティクル構成を確認

**権限による表示制御**：パブリッシャーおよびサブスクライバーの両方でsysadmin権限またはdb_owner権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 449 | Get-DbaReplSubscription | 主機能 | サブスクリプションの取得 |
| 453 | New-DbaReplSubscription | 主機能 | サブスクリプションの作成 |
| 456 | Remove-DbaReplSubscription | 主機能 | サブスクリプションの削除 |
| 446 | Get-DbaReplPublication | 遷移元機能 | パブリケーション情報の取得 |

## 画面種別

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

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Get-DbaReplSubscription -SqlInstance <インスタンス名>`
- `New-DbaReplSubscription -SqlInstance <パブリッシャー> -Database <DB名> -SubscriberSqlInstance <サブスクライバー> -SubscriptionDatabase <DB名> -PublicationName <パブリケーション名> -Type Push`
- `Remove-DbaReplSubscription -SqlInstance <パブリッシャー> -Database <DB名> -PublicationName <パブリケーション名> -SubscriberSqlInstance <サブスクライバー> -SubscriptionDatabase <DB名>`

## 入出力項目

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

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | パブリッシャーSQLインスタンス |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| Database | Object[] | いいえ | 対象データベース |
| PublicationName | String[] | いいえ | 対象パブリケーション名 |
| SubscriberName | DbaInstanceParameter[] | いいえ | サブスクライバーインスタンス |
| SubscriptionDatabase | Object[] | いいえ | サブスクリプションDB名 |
| Type | ValidateSet("Push", "Pull") | いいえ | サブスクリプションタイプ |
| EnableException | switch | いいえ | 例外処理の有効化 |

### New-DbaReplSubscription 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter | はい | パブリッシャーSQLインスタンス |
| SqlCredential | PSCredential | いいえ | パブリッシャー認証情報 |
| Database | String | いいえ | パブリケーションDB |
| SubscriberSqlInstance | DbaInstanceParameter[] | はい | サブスクライバーインスタンス |
| SubscriberSqlCredential | PSCredential | いいえ | サブスクライバー認証情報 |
| SubscriptionDatabase | String | いいえ | サブスクリプションDB |
| PublicationName | String | はい | パブリケーション名 |
| SubscriptionSqlCredential | PSCredential | いいえ | 同期エージェント認証情報 |
| Type | ValidateSet("Push", "Pull") | はい | サブスクリプションタイプ |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

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

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | パブリッシャーコンピュータ名 |
| InstanceName | string | パブリッシャーインスタンス名 |
| SqlInstance | string | 完全パブリッシャーインスタンス名 |
| DatabaseName | string | パブリケーションDB名 |
| PublicationName | string | パブリケーション名 |
| Name | string | サブスクリプション名 |
| SubscriberName | string | サブスクライバーインスタンス名 |
| SubscriptionDBName | string | サブスクリプションDB名 |
| SubscriptionType | string | タイプ（Push/Pull） |

## イベント仕様

### 1-サブスクリプション取得（Get-DbaReplSubscription）

1. SQLインスタンスに接続（Connect-DbaInstance）
2. Get-DbaReplPublicationでパブリケーション一覧を取得
3. Database/PublicationNameでフィルタリング
4. 各パブリケーションのSubscriptionsプロパティを取得
5. SubscriberName/SubscriptionDatabase/Typeでフィルタリング
6. 結果にNotePropertyを追加してパイプラインに出力

### 2-サブスクリプション作成（New-DbaReplSubscription）

1. パブリッシャーに接続しレプリケーションサーバーオブジェクトを取得
2. パブリケーションの存在確認
3. サブスクライバーに接続
4. サブスクリプションデータベースが存在しない場合は自動作成
5. 必要なスキーマが存在しない場合は自動作成
6. パブリケーションタイプ（Transactional/Merge）に応じたサブスクリプションオブジェクト作成
7. AllowPush/AllowPull属性を確認・設定
8. Create()メソッドでサブスクリプションを作成

### 3-サブスクリプション削除（Remove-DbaReplSubscription）

1. パブリケーション情報を取得
2. パブリケーションタイプに応じてTransSubscriptionまたはMergeSubscriptionオブジェクト作成
3. IsExistingObjectで存在確認
4. Remove()メソッドでサブスクリプション削除

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| New-DbaReplSubscription | MSsubscriptions | INSERT | サブスクリプション情報の登録 |
| New-DbaReplSubscription | サブスクリプションDB | CREATE DATABASE | DB未存在時の自動作成 |
| Remove-DbaReplSubscription | MSsubscriptions | DELETE | サブスクリプション情報の削除 |
| Get-DbaReplSubscription | MSsubscriptions | SELECT | サブスクリプション情報の取得 |

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

#### MSsubscriptions（ディストリビューションDB）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | subscriber_name | -SubscriberSqlInstance値 | サブスクライバー名 |
| INSERT | subscriber_db | -SubscriptionDatabase値 | サブスクリプションDB |
| INSERT | subscription_type | 0(Push) or 1(Pull) | タイプ値 |
| INSERT | publication_id | パブリケーションID | 自動取得 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | 警告 | Subscription database {DB} not found on {instance} - will create it | サブスクリプションDB未存在時 |
| MSG002 | 情報 | Creating subscription on {instance} | サブスクリプション作成開始時 |
| MSG003 | 警告 | Didn't find a subscription to the {Publication} publication on {SqlInstance}.{Database} | パブリケーション未存在時 |
| MSG004 | 警告 | Didn't find a subscription to {Publication} on {instance}.{SubscriptionDatabase} | サブスクリプション未存在時 |
| MSG005 | エラー | Publication {Publication} not found on {instance} | パブリケーション未存在時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionでエラーメッセージを表示し、次のインスタンスに継続 |
| パブリケーション未存在 | 警告メッセージを表示し処理をスキップ |
| サブスクリプションDB作成失敗 | Stop-Functionでエラーメッセージを表示し処理を停止 |
| サブスクリプション作成失敗 | Stop-Functionでエラーメッセージを表示し、次のサブスクライバーに継続 |
| サブスクリプション削除失敗 | Stop-Functionでエラーメッセージを表示 |

## 備考

- Pushサブスクリプションはパブリッシャーで管理され、高頻度レプリケーションに適する
- Pullサブスクリプションはサブスクライバーで管理され、サブスクライバー側の制御が必要な場合に使用
- サブスクリプションDB未存在時は自動作成されるが、設定は要確認
- 必要なスキーマもアーティクルの宛先スキーマに基づき自動作成される
- 現在のRemove-DbaReplSubscriptionはPushサブスクリプションのみサポート

---

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

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

### 推奨読解順序

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

サブスクリプションはMicrosoft.SqlServer.Replication.Subscriptionオブジェクトとして表現される。

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

**読解のコツ**: .OUTPUTSセクションでデフォルト表示プロパティを確認。SubscriptionTypeプロパティがPush/Pullを示す。

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

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

**主要処理フロー**:
1. **131-135行目**: Connect-DbaInstanceでサーバー接続
2. **138行目**: Get-DbaReplPublicationでパブリケーション取得
3. **140-146行目**: Database/PublicationNameでフィルタリング
4. **153-166行目**: SubscriberName/SubscriptionDatabase/Typeでフィルタリング
5. **168-173行目**: NotePropertyを追加して出力

#### Step 3: サブスクリプション作成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaReplSubscription.ps1 | `public/New-DbaReplSubscription.ps1` | サブスクリプションDB自動作成（150-163行目） |

**主要処理フロー**:
- **129-133行目**: パブリッシャー接続とレプリケーションサーバー取得
- **135-139行目**: パブリケーション存在確認
- **150-163行目**: サブスクリプションDB未存在時の自動作成
- **174-179行目**: 必要スキーマの自動作成
- **181-251行目**: TransSubscription/MergeSubscriptionの作成分岐
- **194-216行目**: AllowPush/AllowPull属性の設定

#### Step 4: サブスクリプション削除処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Remove-DbaReplSubscription.ps1 | `public/Remove-DbaReplSubscription.ps1` | TransSubscription/MergeSubscriptionの分岐（116-146行目） |

**主要処理フロー**:
- **103-107行目**: パブリケーション存在確認
- **116-130行目**: Transactional/Snapshotサブスクリプション削除
- **132-145行目**: Mergeサブスクリプション削除

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

```
Get-DbaReplSubscription
    │
    ├─ Connect-DbaInstance
    │      └─ SMOサーバーオブジェクト取得
    │
    └─ Get-DbaReplPublication
           └─ Publications.Subscriptionsプロパティ取得

New-DbaReplSubscription
    │
    ├─ Get-DbaReplServer
    │      └─ レプリケーションサーバーオブジェクト
    │
    ├─ Get-DbaReplPublication
    │      └─ パブリケーション存在確認
    │
    ├─ Get-DbaDatabase
    │      └─ サブスクリプションDB存在確認
    │
    ├─ New-DbaDatabase
    │      └─ サブスクリプションDB自動作成
    │
    ├─ Get-DbaDbSchema / New-DbaDbSchema
    │      └─ 必要スキーマの確認・作成
    │
    └─ TransSubscription.Create() / MergeSubscription.Create()
           └─ MSsubscriptionsへのINSERT

Remove-DbaReplSubscription
    │
    ├─ Get-DbaReplPublication
    │      └─ パブリケーション取得
    │
    └─ TransSubscription.Remove() / MergeSubscription.Remove()
           └─ MSsubscriptionsからのDELETE
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ─────▶ SMO Server Object
                            │
                            ▼
                   Get-DbaReplPublication
                            │
                            ▼
                   Publications.Subscriptions ─────▶ Subscription Object[]
                            │
SubscriberName ────────────▶│ (フィルタリング)
SubscriptionDatabase ──────▶│
Type ──────────────────────▶│
                            ▼
                   Select-DefaultView ─────────────▶ 画面出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaReplSubscription.ps1 | `public/Get-DbaReplSubscription.ps1` | ソース | サブスクリプション情報取得 |
| New-DbaReplSubscription.ps1 | `public/New-DbaReplSubscription.ps1` | ソース | サブスクリプション作成 |
| Remove-DbaReplSubscription.ps1 | `public/Remove-DbaReplSubscription.ps1` | ソース | サブスクリプション削除 |
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | 依存 | パブリケーション情報取得 |
| Get-DbaReplServer.ps1 | `public/Get-DbaReplServer.ps1` | 依存 | レプリケーションサーバー取得 |
| New-DbaDatabase.ps1 | `public/New-DbaDatabase.ps1` | 依存 | サブスクリプションDB作成 |
| Get-DbaDbSchema.ps1 | `public/Get-DbaDbSchema.ps1` | 依存 | スキーマ存在確認 |
| New-DbaDbSchema.ps1 | `public/New-DbaDbSchema.ps1` | 依存 | スキーマ自動作成 |
