# 機能設計書 425-Copy-DbaDbQueryStoreOption

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Copy-DbaDbQueryStoreOption`コマンドレットに関する機能設計書である。このコマンドレットは、Query Store構成設定をソースデータベースから複数のターゲットデータベースに複製する機能を提供する。

### 本機能の処理概要

`Copy-DbaDbQueryStoreOption`は、ソースデータベースのQuery Store構成を読み取り、指定された宛先データベースに同じ設定を適用するコマンドレットである。これにより、実績のあるQuery Store設定を環境全体で標準化することができる。

**業務上の目的・背景**：Query Storeは、SQL Server 2016で導入されたクエリパフォーマンス分析機能であり、クエリプラン、実行統計、待機統計などを収集・保存する。環境全体で一貫したQuery Store動作を確保するために、検証済みの設定を複数のデータベースに適用する必要がある。本機能により、DBAは手動設定の手間を省き、設定ミスを防ぎながら、Query Store構成を効率的に展開できる。

**機能の利用シーン**：
- 本番環境の設定を開発・テスト環境に複製する場合
- 新規データベースにベストプラクティス設定を適用する場合
- インスタンス全体のQuery Store設定を標準化する場合
- DR/HAセットアップでの構成同期

**主要な処理内容**：
1. ソースデータベースからQuery Store構成を取得する
2. 宛先データベースのリストを取得・フィルタリングする
3. SQL Serverバージョンに応じた適切なパラメータを構築する
4. Set-DbaDbQueryStoreOptionを使用して設定を適用する
5. 結果を返却する

**関連システム・外部連携**：SQL Server Query Store機能と連携し、sys.database_query_store_optionsシステムビューのデータにアクセスする。

**権限による制御**：ソースおよび宛先インスタンスへのsysadminアクセス、またはデータベースのALTER権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | SQL Server Management Studio - Query Store | 参照画面 | SSMS上でのQuery Store設定に相当 |

## 機能種別

データ複製 / 構成管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Source | DbaInstanceParameter | Yes | ソースSQL Serverインスタンス | 有効なSQL Server接続文字列 |
| SourceSqlCredential | PSCredential | No | ソースインスタンスの代替資格情報 | 有効なPSCredentialオブジェクト |
| SourceDatabase | object | Yes | Query Store設定のコピー元データベース | 存在するデータベース名 |
| Destination | DbaInstanceParameter[] | Yes | 宛先SQL Serverインスタンス | 有効なSQL Server接続文字列 |
| DestinationSqlCredential | PSCredential | No | 宛先インスタンスの代替資格情報 | 有効なPSCredentialオブジェクト |
| DestinationDatabase | object[] | No | 設定を適用する特定のデータベース | AllDatabasesと排他 |
| Exclude | object[] | No | 設定適用から除外するデータベース | なし |
| AllDatabases | switch | No | すべてのユーザーデータベースに適用 | DestinationDatabaseと排他 |
| WhatIf | switch | No | 実行内容を表示するのみ | なし |
| Confirm | switch | No | 実行前に確認を求める | なし |
| EnableException | switch | No | 例外をスローするモードを有効化 | なし |

### 入力データソース

- ソースSQL Serverインスタンスのデータベース
- 宛先SQL Serverインスタンスのデータベース

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| DateTime | DbaDateTime | 操作のタイムスタンプ |
| SourceServer | string | ソースSQL Serverインスタンス名 |
| SourceDatabase | string | ソースデータベース名 |
| SourceDatabaseID | int | ソースデータベースID |
| DestinationServer | string | 宛先SQL Serverインスタンス名 |
| Name | string | 宛先データベース名 |
| DestinationDatabaseID | int | 宛先データベースID |
| Type | string | "QueryStore Configuration"（固定値） |
| Status | string | 操作結果（"Skipped", "Successful", "Failed"） |
| Notes | string | エラーメッセージ（失敗時）またはnull |

### 出力先

- PowerShellパイプライン（標準出力）
- PSCustomObjectとして出力

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   └─ ソースインスタンスへの接続
2. processブロック
   ├─ Test-FunctionInterruptでの中断チェック
   ├─ ソースデータベースのQuery Store設定を取得
   ├─ 各宛先インスタンスの処理
   │   ├─ パラメータ検証（DestinationDatabase/Exclude/AllDatabasesのいずれかが必要）
   │   ├─ 宛先インスタンスへの接続
   │   ├─ 宛先データベースリストの取得・フィルタリング
   │   └─ 各宛先データベースの処理
   │       ├─ ソースと宛先が同一の場合はスキップ
   │       ├─ アクセス不可の場合はスキップ
   │       ├─ バージョンに応じたパラメータ構築
   │       └─ Set-DbaDbQueryStoreOptionで設定適用
   └─ 結果の出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ソースインスタンス接続]
    B --> C{接続成功?}
    C -->|No| Z[終了]
    C -->|Yes| D[Get-DbaDbQueryStoreOption]
    D --> E[各宛先インスタンスを処理]
    E --> F{パラメータ検証}
    F -->|失敗| G[Stop-Function]
    G --> E
    F -->|成功| H[宛先インスタンス接続]
    H --> I[Get-DbaDatabase]
    I --> J[DestinationDatabase/Excludeフィルター]
    J --> K[各宛先DBを処理]
    K --> L{ソースと同一?}
    L -->|Yes| M[スキップ]
    L -->|No| N{アクセス可能?}
    N -->|No| O[スキップ出力]
    N -->|Yes| P{バージョン判定}
    P -->|v13| Q[SQL 2016パラメータ構築]
    P -->|v14| R[SQL 2017パラメータ構築]
    P -->|v15+| S[SQL 2019+パラメータ構築]
    Q --> T[Set-DbaDbQueryStoreOption]
    R --> T
    S --> T
    T --> U{成功?}
    U -->|Yes| V[Successful出力]
    U -->|No| W[Failed出力]
    M --> X{次のDB?}
    O --> X
    V --> X
    W --> X
    X -->|Yes| K
    X -->|No| Y{次のインスタンス?}
    Y -->|Yes| E
    Y -->|No| Z
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パラメータ排他制御 | DestinationDatabase, Exclude, AllDatabasesのいずれかが必要 | すべての実行 |
| BR-002 | システムDB除外 | システムデータベースは自動的に除外 | すべての実行 |
| BR-003 | 自己複製防止 | ソースとターゲットが同一の場合はスキップ | 同一インスタンス・同一DB |
| BR-004 | アクセス不可DB処理 | IsAccessible=falseのDBはスキップ | アクセス不可DB検出時 |
| BR-005 | バージョン別パラメータ | SQL Serverバージョンに応じた設定項目を使用 | すべての実行 |

### 計算ロジック

バージョン別のQuery Storeパラメータ:

**SQL Server 2016 (v13):**
- State, FlushInterval, CollectionInterval, MaxSize, CaptureMode, CleanupMode, StaleQueryThreshold

**SQL Server 2017 (v14):**
- 上記に加えて: MaxPlansPerQuery, WaitStatsCaptureMode

**SQL Server 2019以降 (v15+):**
- 上記に加えて: CustomCapturePolicyExecutionCount, CustomCapturePolicyTotalCompileCPUTimeMS, CustomCapturePolicyTotalExecutionCPUTimeMS, CustomCapturePolicyStaleThresholdHours

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Query Store設定取得 | sys.database_query_store_options | SELECT | ソースDB設定の取得 |
| Query Store設定変更 | sys.database_query_store_options | ALTER | 宛先DB設定の変更 |

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

#### sys.database_query_store_options

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | actual_state_desc | ソースDBから取得 | State設定 |
| SELECT | data_flush_interval_seconds | ソースDBから取得 | FlushInterval設定 |
| SELECT | interval_length_minutes | ソースDBから取得 | CollectionInterval設定 |
| ALTER | desired_state_desc | ソースからコピー | ReadWrite/ReadOnly/Off |
| ALTER | max_storage_size_mb | ソースからコピー | MaxSize設定 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | ソースインスタンス接続失敗 | 接続情報を確認する |
| - | ConnectionError | 宛先インスタンス接続失敗 | 接続情報を確認する（-Continue） |
| - | Stop-Function | パラメータ不足 | DestinationDatabase/Exclude/AllDatabasesのいずれかを指定 |
| - | Stop-Function | マッチするDBなし | スペルを確認して再試行 |

### リトライ仕様

リトライ処理は実装されていない。宛先インスタンスのエラー時は-Continueで次のインスタンスを処理。

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

各データベースのQuery Store設定変更は個別に実行される。明示的なトランザクション制御は実装されていない。

## パフォーマンス要件

特に規定なし。Query Store設定変更は軽量な操作。

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

- SQL Server認証、Windows認証、Azure AD認証をサポート
- 接続資格情報はPSCredentialオブジェクトで安全に管理
- MFAサポートが必要な場合はConnect-DbaInstanceの事前使用を推奨
- sysadminまたはALTER DATABASE権限が必要

## 備考

- SQL Server 2016以降（Version 13以上）が必要（Query Store機能導入バージョン）
- 著者はEnrico van de Laar、Tracy Boggiano
- SupportsShouldProcess対応（WhatIf/Confirm）

---

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

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

### 推奨読解順序

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

Query Store設定オブジェクトの構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Copy-DbaDbQueryStoreOption.ps1 | `public/Copy-DbaDbQueryStoreOption.ps1` | .OUTPUTSセクション（72-90行目）で出力オブジェクトの構造を理解 |

**読解のコツ**: 出力はPSCustomObjectであり、マイグレーション操作の結果を表す。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Copy-DbaDbQueryStoreOption.ps1 | `public/Copy-DbaDbQueryStoreOption.ps1` | パラメータ定義（102-116行目）で入力の受け取り方を確認 |

**主要処理フロー**:
1. **118-124行目**: beginブロックでソースインスタンス接続
2. **127-131行目**: ソースDB設定の取得
3. **135-252行目**: 宛先インスタンス・DBごとの処理

#### Step 3: バージョン別処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Copy-DbaDbQueryStoreOption.ps1 | `public/Copy-DbaDbQueryStoreOption.ps1` | バージョン分岐ロジック（192-239行目） |

**主要処理フロー**:
- **192-204行目**: SQL Server 2016 (v13)のパラメータ
- **205-219行目**: SQL Server 2017 (v14)のパラメータ
- **220-238行目**: SQL Server 2019以降 (v15+)のパラメータ

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

```
Copy-DbaDbQueryStoreOption
    │
    ├─ Connect-DbaInstance (Source)
    │      └─ ソースSQL Server接続
    │
    ├─ Get-DbaDbQueryStoreOption
    │      └─ ソースDB設定取得
    │
    ├─ Get-DbaDatabase (Source)
    │      └─ ソースDBオブジェクト取得
    │
    ├─ Connect-DbaInstance (Destination)
    │      └─ 宛先SQL Server接続
    │
    ├─ Get-DbaDatabase (Destination)
    │      └─ 宛先DBリスト取得
    │
    └─ Set-DbaDbQueryStoreOption
           └─ Query Store設定適用
```

### データフロー図

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

Source        ───────▶ Connect-DbaInstance
SourceDatabase            │
                          ▼
                 Get-DbaDbQueryStoreOption ───────▶ $SourceQSConfig
                          │
                          ▼
Destination   ───────▶ Connect-DbaInstance
                          │
                          ▼
                 Get-DbaDatabase (ExcludeSystem)
                          │
                          ▼
               DestinationDatabase/Exclude フィルター
                          │
                          ▼
               バージョン判定 ───▶ パラメータ構築
                          │
                          ▼
                 Set-DbaDbQueryStoreOption
                          │
                          ▼
                   結果オブジェクト ───────▶ PSCustomObject[]
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Copy-DbaDbQueryStoreOption.ps1 | `public/Copy-DbaDbQueryStoreOption.ps1` | ソース | メイン機能の実装 |
| Get-DbaDbQueryStoreOption.ps1 | `public/Get-DbaDbQueryStoreOption.ps1` | ソース | Query Store設定取得 |
| Set-DbaDbQueryStoreOption.ps1 | `public/Set-DbaDbQueryStoreOption.ps1` | ソース | Query Store設定変更 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `private/Select-DefaultView.ps1` | ソース | 出力プロパティの制限 |
