# 画面設計書 55-データベースクローン

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるデータベースクローン（Database Clone）機能の設計仕様を記載したものです。DBCC CLONEDATABASEを使用してスキーマと統計情報のみを含む軽量なデータベースクローンを作成する機能を提供します。

### 本画面の処理概要

本機能は、SQL ServerのDBCC CLONEDATABASEコマンドを使用して、スキーマと統計情報のみを含むデータベースクローンを作成するPowerShellコマンドを提供します。作成されるクローンにはテーブルデータは含まれませんが、オプティマイザが実行プランを生成するために必要なすべての統計情報が保持されます。

**業務上の目的・背景**：データベースクローンは、パフォーマンストラブルシューティングにおいて非常に有用です。クエリ実行プランの分析やオプティマイザの動作検証を、本番データをコピーせずに行うことができます。これにより、ベンダーへのサポートケース提供、テスト環境でのパフォーマンス問題の再現、データベース構造の共有などが、ストレージコストを抑えながら実現できます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `Invoke-DbaDbClone` - データベースクローンの作成

**主要な操作・処理内容**：
1. ソースデータベースの選択
2. クローンデータベース名の指定
3. 列ストアインデックス統計の更新（オプション）
4. DBCC CLONEDATABASEの実行
5. 統計情報やQuery Storeの除外（オプション）
6. クローンデータベースオブジェクトの取得と出力

**画面遷移**：本機能はCLIコマンドであり、Get-DbaDatabase からパイプライン入力を受け取ることができます。作成されたクローンデータベースは、Get-DbaDatabase等で通常のデータベースとして参照できます。

**権限による表示制御**：データベースクローンの作成には対象データベースへの適切な権限が必要です。また、システムデータベースはクローン対象外です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 165 | Invoke-DbaDbClone | 主機能 | データベースクローンの作成 |

## 画面種別

実行（CLI）

## URL/ルーティング

PowerShellコマンドとして以下のコマンドレット名でアクセス:
- `Invoke-DbaDbClone`

## 入出力項目

### Invoke-DbaDbClone パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter[] | 対象SQL Serverインスタンス |
| SqlCredential | No | PSCredential | 認証用資格情報 |
| Database | No | string[] | ソースデータベース名 |
| InputObject | No | Database[] | パイプライン入力 |
| CloneDatabase | No | string[] | クローンデータベース名（省略時は_clone接尾辞） |
| ExcludeStatistics | No | switch | 統計情報を除外 |
| ExcludeQueryStore | No | switch | Query Storeデータを除外 |
| UpdateStatistics | No | switch | 列ストアインデックス統計を更新 |
| EnableException | No | switch | 例外を有効化 |

## 表示項目

### Invoke-DbaDbClone 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLサーバーインスタンス名 |
| SqlInstance | string | フルインスタンス名 |
| Name | string | クローンデータベース名 |
| Status | string | データベースステータス |
| IsAccessible | bool | アクセス可能フラグ |
| RecoveryModel | string | リカバリモデル |
| LogReuseWaitStatus | string | ログ再利用待機ステータス |
| Size | decimal | データベースサイズ（MB） |
| Owner | string | データベース所有者 |
| Collation | string | 照合順序 |
| Encrypted | bool | TDE暗号化フラグ |

## イベント仕様

### 1-データベースクローン作成

1. ソースデータベースオブジェクトの取得
2. SQL Serverバージョン互換性の確認
3. システムデータベースの除外確認
4. 列ストアインデックス統計の更新（UpdateStatistics指定時）
5. 宛先クローン名の既存確認
6. DBCC CLONEDATABASE コマンドの実行
7. サーバーデータベースコレクションのリフレッシュ
8. 作成されたクローンデータベースの取得と出力

### 2-列ストアインデックス統計更新

1. 列ストアインデックスの列挙（sys.indexes）
2. 各インデックスのDBCC SHOW_STATISTICS実行
3. stats_streamを使用した統計情報の更新
4. Microsoft Tiger Teamの手法に基づく処理

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbClone | - | DBCC CLONEDATABASE | スキーマ専用クローンの作成 |
| UpdateStatistics | sys.indexes | UPDATE STATISTICS | 列ストアインデックス統計の更新 |

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

本機能はDBCC CLONEDATABASEコマンドを実行し、新しいデータベースを作成します。ソースデータベースのデータは変更されません。

#### 作成されるクローンデータベースの特徴

| 項目 | 説明 |
|-----|------|
| スキーマ | ソースと同一（テーブル、インデックス、ビュー、プロシージャ等） |
| 統計情報 | ソースからコピー（ExcludeStatistics未指定時） |
| Query Store | ソースからコピー（ExcludeQueryStore未指定時） |
| テーブルデータ | 含まれない（空のテーブル） |
| ファイルサイズ | ソースより大幅に小さい |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | エラー | Unsupported version for $instance. SQL Server 2012 SP4 and above required. | SQL Server 2012 SP4未満 |
| MSG-002 | エラー | Unsupported version for $instance. SQL Server 2014 SP2 and above required. | SQL Server 2014 SP2未満 |
| MSG-003 | エラー | Unsupported version for $instance. SQL Server 2016 SP1 and above required. | SQL Server 2016 SP1未満 |
| MSG-004 | エラー | Only user databases are supported | システムデータベースの場合 |
| MSG-005 | エラー | Destination clone database $clonedb already exists | クローン名が既存 |
| MSG-006 | エラー | You must specify a database name if you did not pipe a database | Database未指定時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| バージョン非互換 | Stop-Functionで処理停止、バージョン要件を含むエラーメッセージ出力 |
| システムデータベース | Stop-Functionで処理停止、ユーザーDBのみサポートのメッセージ |
| クローン名重複 | Stop-Functionで処理停止、既存データベース名のエラー |
| 統計更新失敗 | Stop-Functionで処理停止、詳細エラー出力 |
| DBCC CLONEDATABASE失敗 | Stop-Functionで処理停止、詳細エラー出力 |

## 備考

- DBCC CLONEDATABASEはSQL Server 2012 SP4、2014 SP2、2016 SP1以降で利用可能
- ExcludeStatisticsオプションはSQL Server 2014 SP2 CU3+または2016 SP1+で利用可能
- ExcludeQueryStoreオプションはSQL Server 2016 SP1以降で利用可能
- 作成されるクローンは読み取り専用モードで作成される
- クローンにはデータが含まれないため、実行プラン分析には適しているがクエリ実行には不適

---

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

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

### 推奨読解順序

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

DBCC CLONEDATABASEの動作と出力構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Database | Microsoft.SqlServer.Management.Smo | Databaseオブジェクトのプロパティ |
| 1-2 | DBCC CLONEDATABASE | T-SQL | クローン作成コマンドの構文 |

**読解のコツ**: クローンデータベースは通常のDatabaseオブジェクトとして返されます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbClone.ps1 | `public/Invoke-DbaDbClone.ps1` | クローン作成のメインロジック |

**主要処理フロー (Invoke-DbaDbClone)**:
1. **行126-130**: begin ブロック - パラメータ検証
2. **行131-169**: 列ストアインデックス統計更新SQL定義
3. **行186-190**: バージョン最小要件の定義
4. **行192-196**: SqlInstance指定時のInputObject設定
5. **行198-246**: 各データベースに対するクローン処理
6. **行250-268**: 各クローン名に対するDBCC CLONEDATABASE実行

#### Step 3: バージョン互換性を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbClone.ps1 | `public/Invoke-DbaDbClone.ps1` 行186-230 | バージョンチェックロジック |

**バージョン要件**:
- SQL Server 2012: SP4 (11.0.7001) 以上
- SQL Server 2014: SP2 (12.0.5000) 以上
- SQL Server 2016: SP1 (13.0.4001) 以上
- ExcludeStatistics: SQL Server 2014 SP2 CU3 (12.0.5538) 以上
- ExcludeQueryStore: SQL Server 2016 SP1 以上

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

```
Invoke-DbaDbClone
    |
    +-- パラメータ検証
    |       +-- Database指定チェック
    |
    +-- Get-DbaDatabase (SqlInstance指定時)
    |
    +-- バージョン互換性チェック
    |       +-- SQL 2012 SP4, 2014 SP2, 2016 SP1
    |
    +-- システムデータベースチェック
    |
    +-- 列ストアインデックス統計更新
    |       +-- $db.Invoke($sqlStats) (UpdateStatistics時)
    |
    +-- クローン名重複チェック
    |
    +-- DBCC CLONEDATABASE実行
    |       +-- $db.Invoke($sql)
    |
    +-- データベースコレクションリフレッシュ
    |       +-- $server.Databases.Refresh()
    |
    +-- 結果出力
            +-- Get-DbaDatabase (クローンDB取得)
```

### データフロー図

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

SqlInstance/     ------>  Get-DbaDatabase
InputObject               |
                         v
                   バージョン互換性チェック
                         |
                         v
UpdateStatistics ------>  列ストアインデックス
                         統計更新（オプション）
                         |
                         v
CloneDatabase    ------>  クローン名決定
                         (_clone接尾辞または指定名)
                         |
                         v
ExcludeStatistics -->    DBCC CLONEDATABASE
ExcludeQueryStore -->    WITH オプション構築
                         |
                         v
                   $db.Invoke(DBCC CLONEDATABASE)
                         |
                         v
                   $server.Databases.Refresh()
                         |
                         v
                   Get-DbaDatabase  ----->  Database オブジェクト
                   (クローンDB取得)          (クローンデータベース)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbClone.ps1 | `public/Invoke-DbaDbClone.ps1` | ソース | クローン作成コマンド |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
