# 画面設計書 205-DACパッケージ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるDACパッケージ管理機能（DACPAC/BACPACのエクスポート・作成・公開）の設計仕様を定義するものである。

### 本画面の処理概要

DACパッケージ機能は、SQL Serverデータベースのスキーマとデータをパッケージ化（DACPAC/BACPAC）し、バージョン管理、マイグレーション、デプロイメントを支援する機能群を提供する。CI/CDパイプラインやデータベースDevOpsの中核機能である。

**業務上の目的・背景**：データベースの変更管理とデプロイメント自動化は、現代のアプリケーション開発において不可欠である。DACPACはスキーマ定義を、BACPACはスキーマとデータの両方をパッケージ化する。これにより、開発環境で作成したデータベース構造を本番環境へ一貫して展開でき、環境間の差異を最小化できる。また、データベースのスナップショットとしてバージョン管理システムに格納することで、変更履歴の追跡と復元が可能になる。

**画面へのアクセス方法**：PowerShellコンソールから`Export-DbaDacPackage`（エクスポート）、`New-DbaDacPackage`（作成）、`Publish-DbaDacPackage`（公開）コマンドを実行する。

**主要な操作・処理内容**：
1. データベースからDACPAC/BACPACのエクスポート（Export-DbaDacPackage）
2. DACパッケージの新規作成（New-DbaDacPackage）
3. DACパッケージのデプロイメント（Publish-DbaDacPackage）
4. テーブルフィルタリングによる部分エクスポート
5. DacOptionによるエクスポート/デプロイメントオプションの制御
6. スクリプト生成のみ（ScriptOnly）モード

**画面遷移**：
- 入力元：Export-DbaDacPackageからPublish-DbaDacPackageへのパイプライン
- 出力先：生成されたDACPAC/BACPACファイル、デプロイされたデータベース
- 関連機能：New-DbaDacOption、New-DbaDacProfile

**権限による表示制御**：エクスポートにはデータベース読み取り権限、デプロイメントにはデータベース作成・変更権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 60 | Export-DbaDacPackage | 主機能 | DACパッケージのエクスポート |
| 62 | New-DbaDacPackage | 主機能 | DACパッケージの作成 |
| 64 | Publish-DbaDacPackage | 主機能 | DACパッケージの公開 |
| 61 | New-DbaDacOption | 補助機能 | DACオプションの作成 |
| 63 | New-DbaDacProfile | 補助機能 | DACプロファイルの作成 |

## 画面種別

コマンドラインインターフェース（CLI）/ デプロイメント

## URL/ルーティング

```powershell
# エクスポート
Export-DbaDacPackage -SqlInstance <インスタンス> -Database <DB名> [-Path <出力先>]

# デプロイメント
Publish-DbaDacPackage -SqlInstance <インスタンス> -Database <DB名> -Path <DACPACパス>
```

## 入出力項目

### Export-DbaDacPackage パラメータ

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| SqlInstance | DbaInstance[] | Yes | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | - | SQL認証用資格情報 |
| Path | string | No | DbatoolsExport | 出力ディレクトリ |
| FilePath | string | No | - | 完全な出力ファイルパス |
| Database | object[] | No | - | 対象データベース |
| ExcludeDatabase | object[] | No | - | 除外データベース |
| AllUserDatabases | switch | No | $false | 全ユーザーデータベース |
| Type | string | No | Dacpac | パッケージ種別（Dacpac/Bacpac） |
| Table | string[] | No | - | 含めるテーブル |
| DacOption | object | No | - | DACオプションオブジェクト |
| ExtendedParameters | string | No | - | SqlPackage追加パラメータ |
| ExtendedProperties | string | No | - | SqlPackage追加プロパティ |
| EnableException | switch | No | $false | 例外の有効化 |

### Publish-DbaDacPackage パラメータ

| パラメータ名 | 型 | 必須 | 既定値 | 説明 |
|-------------|-----|------|--------|------|
| SqlInstance | DbaInstance[] | No | - | 対象SQLインスタンス |
| SqlCredential | PSCredential | No | - | SQL認証用資格情報 |
| Path | string | Yes | - | DACPACファイルパス |
| PublishXml | string | No | - | 公開プロファイルXMLパス |
| Database | string[] | Yes | - | 対象データベース |
| ConnectionString | string[] | No | - | 接続文字列 |
| GenerateDeploymentReport | switch | No | $false | デプロイメントレポート生成 |
| ScriptOnly | switch | No | $false | スクリプト生成のみ |
| Type | string | No | Dacpac | パッケージ種別 |
| DacOption | object | No | - | DACオプションオブジェクト |
| OutputPath | string | No | DbatoolsExport | スクリプト出力先 |
| IncludeSqlCmdVars | switch | No | $false | SqlCmd変数の置換 |
| EnableException | switch | No | $false | 例外の有効化 |
| DacFxPath | string | No | - | DacFx DLLパス |

## 表示項目

### Export-DbaDacPackage 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| Path | string | 出力ファイルパス |
| Elapsed | prettytimespan | 経過時間 |
| Result | string | 実行結果メッセージ |

### Publish-DbaDacPackage 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| Database | string | データベース名 |
| Dacpac/Bacpac | string | パッケージファイルパス |
| PublishXml | string | 使用したプロファイルパス |
| Result | string | 実行結果メッセージ |
| DatabaseScriptPath | string | 生成されたスクリプトパス |
| MasterDbScriptPath | string | masterDBスクリプトパス |
| DeploymentReport | string | デプロイメントレポートパス |
| DeployOptions | object | 使用したデプロイオプション |
| SqlCmdVariableValues | string[] | 適用したSqlCmd変数 |

## イベント仕様

### 1-エクスポートイベント（Export-DbaDacPackage）

1. SQLインスタンスへの接続
2. SQL Serverバージョン確認（2008 R2以上）
3. データベースの列挙（OnlyAccessible、ExcludeSystem）
4. テーブルフィルタの構築
5. DacServicesオブジェクトの作成
6. Extract/Export実行（DacFx API or SqlPackage.exe）
7. 結果ファイルの返却

### 2-デプロイメントイベント（Publish-DbaDacPackage）

1. DACPACファイルの読み込み
2. 公開プロファイルの読み込み（指定時）
3. デプロイオプションの構築
4. SqlCmd変数の置換（指定時）
5. Publish/Import実行
6. スクリプト/レポートの生成（指定時）
7. 結果の返却

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Export-DbaDacPackage | 全オブジェクト | SELECT | スキーマ/データの読み取り |
| Publish-DbaDacPackage | 全オブジェクト | CREATE/ALTER/DROP | スキーマ変更の適用 |

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

#### Publish-DbaDacPackage によるデータベース更新

| 操作 | 対象 | 処理内容 | 備考 |
|-----|-----|---------|------|
| CREATE | テーブル/ビュー/プロシージャ等 | 新規オブジェクト作成 | DACPACに存在しDBに存在しないもの |
| ALTER | テーブル/ビュー/プロシージャ等 | オブジェクト変更 | スキーマ差異の解消 |
| DROP | テーブル/ビュー/プロシージャ等 | オブジェクト削除 | DropObjectsNotInSource時 |

## メッセージ仕様

| 種別 | メッセージ | 条件 |
|------|----------|------|
| エラー | "SqlPackage.exe is required when using -ExtendedParameters or -ExtendedProperties..." | SqlPackage未インストール時 |
| エラー | "You must specify databases to execute against..." | データベース未指定時 |
| エラー | "Export-DbaDacPackage requires SQL Server 2008 R2 or higher" | サポート外バージョン |
| エラー | "Databases not found on $instance" | データベースが見つからない |
| エラー | "Could not connect to the connection string" | 接続失敗時 |
| エラー | "$Path not found." | ファイルが見つからない |
| 警告 | "Seems like the attempt to publish/script may have failed..." | デプロイ失敗の可能性 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionでエラー記録、Continue |
| バージョン不足 | Stop-Functionでメッセージ出力、Continue |
| ファイル未検出 | Stop-Functionでエラー、return |
| DacFxエラー | Stop-Functionでエラー記録、Continue |

## 備考

- SQL Server 2008 R2以上が必要（DACフレームワーク要件）
- DacFx APIまたはSqlPackage.exeを使用
- スレッドセーフなデータベース列挙のためInvoke-DbaQueryを使用
- Bacpacはスキーマとデータの両方を含む

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とDacOptionの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | 出力オブジェクト構造（行361-369） |
| 1-2 | Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | 出力オブジェクト構造（行386-400） |

**読解のコツ**: DacOptionパラメータとNew-DbaDacOptionの関係に注目。TypeとActionの組み合わせで異なるオプションクラスが生成される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | パラメータ定義（行121-144） |
| 2-2 | Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | パラメータ定義（行146-168） |

**主要処理フロー（Export）**:
1. **行145-156**: beginブロックでSqlPackageパスチェック
2. **行161-169**: データベース指定バリデーション
3. **行208-211**: SQL Serverバージョンチェック
4. **行287-298**: DacServicesによるエクスポート

#### Step 3: DacFx API使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | DacServices使用（行289-322） |
| 3-2 | Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | DacServices使用（行330-358） |

**主要処理フロー**:
- **Export**: DacServices.Extract() / DacServices.ExportBacpac()
- **Publish**: DacServices.Publish() / DacServices.ImportBacpac()

#### Step 4: SqlPackage.exe使用を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | SqlPackage実行（行324-360） |

**主要処理フロー**:
- **行329**: SqlPackage引数構築
- **行332-350**: Process.Start()でコマンド実行
- **行357-358**: ExitCodeチェック

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

```
Export-DbaDacPackage
    |
    +-- begin{}
    |      +-- Test-ExportDirectory
    |      +-- Get-DbaSqlPackagePath (CMD時)
    |
    +-- process{}
           +-- Connect-DbaInstance
           +-- バージョンチェック (10.50以上)
           +-- Invoke-DbaQuery (データベース列挙)
           +-- foreach データベース
                  +-- DacServices作成
                  |      +-- Extract() / ExportBacpac()
                  |
                  +-- または SqlPackage.exe
                         +-- Process.Start()

Publish-DbaDacPackage
    |
    +-- begin{}
    |      +-- Convert-ConnectionString
    |
    +-- process{}
           +-- DacPackage.Load() / BacPackage.Load()
           +-- New-DbaDacOption (オプション構築)
           +-- foreach ConnectionString
                  +-- DacServices作成
                  +-- Publish() / ImportBacpac()
                  +-- または Script()
```

### データフロー図

```
[Export]

Database ------> DacServices.Extract() ------> DACPAC/BACPAC ファイル
                        |
                 DacExtractOptions
                 (CommandTimeout等)

[Publish]

DACPAC/BACPAC ------> DacServices.Publish() ------> Database
      |                       |
PublishXml              PublishOptions
(プロファイル)           (DeployOptions)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | ソース | エクスポートコマンド |
| Publish-DbaDacPackage.ps1 | `public/Publish-DbaDacPackage.ps1` | ソース | 公開コマンド |
| New-DbaDacOption.ps1 | `public/New-DbaDacOption.ps1` | ソース | オプション作成 |
| New-DbaDacProfile.ps1 | `public/New-DbaDacProfile.ps1` | ソース | プロファイル作成 |
| Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | ソース | SqlPackageインストール |
