# 帳票設計書 16-Export-DbaDacPackage

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Export-DbaDacPackage` コマンドに関する帳票設計書です。このコマンドは、データベースからDACPACまたはBACPACパッケージをエクスポートする機能を提供します。

### 本帳票の処理概要

Export-DbaDacPackageは、SQL ServerデータベースからDAC（Data-tier Application）パッケージを生成するコマンドです。DACPACはスキーマ定義のみ、BACPACはスキーマとデータの両方を含むパッケージファイルを作成します。Microsoft DacFx APIまたはSqlPackage.exeを使用してパッケージを生成します。

**業務上の目的・背景**：データベースのバージョン管理、環境間移行、デプロイメント自動化において、データベース構造をポータブルな形式で保存する必要があります。DACPACはスキーマ変更の追跡やCI/CDパイプラインでのデプロイメントに適しており、BACPACはデータを含む完全なデータベースコピーの作成に使用されます。本コマンドにより、SSMSを使用せずにスクリプトベースでパッケージ生成が可能になります。

**帳票の利用シーン**：
- データベーススキーマのバージョン管理（ソース管理システムへの格納）
- 開発・テスト・本番環境間のデータベース移行
- CI/CDパイプラインでのデプロイメントアーティファクト生成
- データベースバックアップ（BACPACでデータ含む）
- スキーマ比較・差分デプロイメントの準備
- 災害復旧用のオフサイトスキーマバックアップ

**主要な出力内容**：
1. DACPACファイル（スキーマのみ）
2. BACPACファイル（スキーマ + データ）
3. 処理結果情報（パス、経過時間、結果メッセージ）

**帳票の出力タイミング**：PowerShellコンソールまたはスクリプトからコマンド実行時に即座に出力されます。

**帳票の利用者**：データベース管理者（DBA）、DevOpsエンジニア、アプリケーション開発者、リリースマネージャー

## 帳票種別

データパッケージファイル（DACPAC / BACPAC形式）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | PowerShellコンソール | コマンドライン | Export-DbaDacPackage コマンド実行 |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | DACPAC / BACPAC（ZIP圧縮形式） |
| 用紙サイズ | N/A（バイナリファイル） |
| 向き | N/A |
| ファイル名 | {ServerName}-{DatabaseName}-{timestamp}-dacpackage.{dacpac/bacpac} |
| 出力方法 | ファイル保存 |
| 文字コード | バイナリ |

### パッケージ固有設定

| 項目 | 内容 |
|-----|------|
| DACPAC | スキーマ定義のみ（テーブル、ビュー、プロシージャ等） |
| BACPAC | スキーマ + テーブルデータ |
| 圧縮形式 | ZIP |
| 内部形式 | XML（model.xml）+ データファイル |

## 帳票レイアウト

### レイアウト概要

バイナリパッケージファイルとして出力されます。

```
┌─────────────────────────────────────┐
│      DACPAC/BACPAC構造              │
│   ┌───────────────────────────────┐ │
│   │   [Content_Types].xml         │ │
│   │   model.xml（スキーマ定義）    │ │
│   │   DacMetadata.xml             │ │
│   │   Origin.xml                  │ │
│   │   Data/（BACPACのみ）          │ │
│   └───────────────────────────────┘ │
└─────────────────────────────────────┘
```

### コマンド出力オブジェクト

| No | 項目名 | 説明 | データ取得元 | 表示形式 |
|----|-------|------|-------------|---------|
| 1 | ComputerName | コンピューター名 | Server | 文字列 |
| 2 | InstanceName | インスタンス名 | Server | 文字列 |
| 3 | SqlInstance | フルインスタンス名 | Server | 文字列 |
| 4 | Database | データベース名 | パラメータ | 文字列 |
| 5 | Path | 出力ファイルパス | Get-ExportFilePath | 文字列 |
| 6 | Elapsed | 経過時間 | Stopwatch | TimeSpan |
| 7 | Result | 処理結果メッセージ | DacServices出力 | 文字列 |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| SqlInstance | 対象SQL Serverインスタンス | Yes |
| Database | 対象データベース | Yes（またはAllUserDatabases） |
| AllUserDatabases | 全ユーザーデータベース | No |
| ExcludeDatabase | 除外データベース | No |
| Type | パッケージタイプ（Dacpac/Bacpac） | No（デフォルト: Dacpac） |
| Table | 対象テーブル（部分エクスポート） | No |

### ソート順

| 優先度 | 項目 | 昇順/降順 |
|-------|------|---------|
| 1 | データベース名 | クエリ結果順 |

### 改ページ条件

N/A（バイナリファイル出力のため）

## データベース参照仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 結合条件 |
|-----------|------|---------|
| sys.databases | データベース一覧 | state = 0（ONLINE） |
| 全スキーマオブジェクト | DacFx経由 | データベース内全オブジェクト |

### テーブル別参照項目詳細

#### sys.databases

| 参照項目（カラム名） | 帳票項目との対応 | 取得条件 | 備考 |
|-------------------|----------------|---------|------|
| name | データベース名 | database_id > 4, state = 0 | システムDB除外 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| Elapsed | Stopwatch.Elapsed | - | TimeSpan形式 |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[Export-DbaDacPackage実行] --> B{パラメータセット判定}
    B -->|SMO| C[DacFx API使用]
    B -->|CMD| D[SqlPackage.exe使用]
    C --> E[Connect-DbaInstance]
    D --> E
    E --> F[Invoke-DbaQueryでDB一覧取得]
    F --> G{Database/AllUserDatabases?}
    G -->|指定| H[フィルタ適用]
    G -->|All| I[全ユーザーDB対象]
    H --> J[ループ: 各データベース]
    I --> J
    J --> K{Type?}
    K -->|Dacpac| L[DacServices.Extract]
    K -->|Bacpac| M[DacServices.ExportBacpac]
    L --> N[ファイル出力]
    M --> N
    N --> O[結果オブジェクト生成]
    O --> P{次DB?}
    P -->|Yes| J
    P -->|No| Q[終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| パラメータエラー | Database/AllUserDatabases未指定 | "You must specify databases to execute against..." | パラメータ指定 |
| バージョンエラー | SQL Server 2008 R2未満 | "Export-DbaDacPackage requires SQL Server 2008 R2 or higher..." | サーバーアップグレード |
| オプションエラー | DacOptionの型不一致 | "Microsoft.SqlServer.Dac.DacExtractOptions object type is expected..." | 正しいオプション指定 |
| SqlPackageエラー | SqlPackage.exe未インストール | "SqlPackage.exe is required when using -ExtendedParameters..." | Install-DbaSqlPackage実行 |
| 接続エラー | 接続文字列エラー | "Could not connect to the connection string..." | 接続情報確認 |
| 抽出エラー | DacServices失敗 | "DacServices extraction failure" | データベース確認 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | データベースサイズに依存 |
| 目標出力時間 | サイズ依存（DacOption.CommandTimeoutで制御） |
| 同時出力数上限 | 制限なし（リソース依存） |

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

- SQL Server 2008 R2以上が必要（DAC Framework要件）
- db_owner または VIEW DEFINITION権限が必要
- BACPACにはテーブルデータが含まれるため機密データの取り扱いに注意
- SqlCredentialはSQL認証のみサポート
- 出力ファイルのアクセス権限に注意

## 備考

- DacOptionでコマンドタイムアウト設定可能
- Tableパラメータで部分エクスポート可能
- ExtendedParameters/ExtendedPropertiesはSqlPackage.exe使用時のみ
- スレッドセーフなデータベース列挙のためInvoke-DbaQuery使用
- 三部構成参照（外部DB参照）がある場合は抽出失敗の可能性

---

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

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

### 推奨読解順序

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

DacFx APIとDacServicesの仕組みを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | パラメータ定義（行121-144）でDacOption, Type等を確認 |

**読解のコツ**: ParameterSetでSMO（DacFx API）とCMD（SqlPackage.exe）の使い分けを理解する

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | beginブロック（行145-157） |
| 2-2 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | processブロック（行158-372） |

**主要処理フロー**:
1. **行145-157**: SqlPackage.exeパス取得（CMDモード時）
2. **行161-164**: パラメータ検証
3. **行171-181**: DacOption型検証
4. **行201-211**: Connect-DbaInstanceとバージョンチェック
5. **行219-267**: Invoke-DbaQueryでデータベース列挙

#### Step 3: パッケージ生成処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | DacFx処理（行288-323） |
| 3-2 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | SqlPackage処理（行324-360） |

**主要処理フロー**:
- **行289-293**: DacServices初期化
- **行294-298**: DacOption生成（未指定時）
- **行300**: Message イベントハンドラ登録
- **行302-312**: DACPAC Extract
- **行313-322**: BACPAC ExportBacpac
- **行324-360**: SqlPackage.exe プロセス実行

#### Step 4: 結果出力を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | 結果オブジェクト（行361-369） |

**主要処理フロー**:
- **行361-369**: PSCustomObject生成
- **行369**: Select-DefaultViewで表示プロパティ制御

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

```
Export-DbaDacPackage
    │
    ├─ Test-ExportDirectory (begin)
    │      └─ パス存在確認
    │
    ├─ Get-DbaSqlPackagePath (CMDモード)
    │      └─ SqlPackage.exeパス取得
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ Invoke-DbaQuery
    │      └─ データベース一覧取得（スレッドセーフ）
    │
    ├─ New-DbaDacOption
    │      └─ DacOption生成
    │
    ├─ DacServices.Extract() [DACPAC]
    │      └─ スキーマ抽出
    │
    ├─ DacServices.ExportBacpac() [BACPAC]
    │      └─ スキーマ+データ抽出
    │
    ├─ Get-ExportFilePath
    │      └─ 出力ファイルパス決定
    │
    └─ Process.Start() [CMDモード]
           └─ SqlPackage.exe実行
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ────────▶ Server Object
                            │
Database ──────────▶ Invoke-DbaQuery ────────────▶ Database List
                            │
                            ▼
DacOption ─────────▶ DacServices初期化 ──────────▶ DacServices Object
                            │
                            ▼
Type ──────────────▶ Extract/ExportBacpac ───────▶ DACPAC/BACPAC File
                            │
                            ▼
                     PSCustomObject ─────────────▶ Result Object
                            │
                            ▼
                     Select-DefaultView ─────────▶ Console Output
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Export-DbaDacPackage.ps1 | `public/Export-DbaDacPackage.ps1` | ソース | メイン処理 |
| Export-DbaDacPackage.Tests.ps1 | `tests/Export-DbaDacPackage.Tests.ps1` | テスト | 単体テスト |
| New-DbaDacOption.ps1 | `public/New-DbaDacOption.ps1` | ソース | DacOption生成 |
| Get-DbaSqlPackagePath.ps1 | `private/Get-DbaSqlPackagePath.ps1` | ソース | SqlPackage.exeパス取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | DB接続 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | ソース | クエリ実行 |
| Get-ExportFilePath.ps1 | `private/Get-ExportFilePath.ps1` | ソース | 出力パス決定 |
| Test-ExportDirectory.ps1 | `private/Test-ExportDirectory.ps1` | ソース | ディレクトリ検証 |
