# 機能設計書 322-Install-DbaSqlPackage

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `Install-DbaSqlPackage` 機能の設計書である。Microsoft SqlPackageユーティリティをダウンロード・インストールし、DACPAC（Data-tier Application Component Package）操作のための前提条件を整備する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：データベースDevOpsワークフローやCI/CDパイプラインにおいて、スキーマ変更のデプロイ、DACPACファイルの作成・発行は重要なプロセスである。SqlPackageはMicrosoftが提供するコマンドラインユーティリティで、これらの操作を自動化するために必須のツールである。本機能は、SqlPackageのインストールを自動化し、Import-DbaDacpac、Export-DbaDacpac、Publish-DbaDacpac、Get-DbaDacpacなどのdbatools関数の利用を可能にする。

**機能の利用シーン**：新規環境でのdbatools導入時、CI/CDパイプラインのセットアップ、DACPAC操作を行う開発環境の構築、オフライン環境でのSqlPackageインストール、複数サーバーへの一括展開などで利用される。

**主要な処理内容**：
1. 既存のSqlPackageインストール確認
2. プラットフォーム（Windows/Linux/macOS）に応じたダウンロードURLの決定
3. MicrosoftからSqlPackageのダウンロード（ZIPまたはMSI）
4. インストール（ZIP展開またはMSI実行）
5. 実行権限の設定（Unix系のみ）
6. インストール結果の検証と返却

**関連システム・外部連携**：
- Microsoft ダウンロードサイト（aka.ms/sqlpackage-*）
- Get-DbaSqlPackagePath（既存インストール確認）
- Import-DbaDacpac、Export-DbaDacpac、Publish-DbaDacpac（利用先）

**権限による制御**：AllUsersスコープまたはMSIインストール時は管理者権限が必要。CurrentUserスコープのZIPインストールは一般ユーザーで実行可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主機能 | PowerShellコマンドラインからの実行 |

## 機能種別

インストール処理 / ファイル展開

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| Path | string | No | インストール先カスタムパス | - |
| Scope | string | No | インストールスコープ（CurrentUser/AllUsers） | ValidateSet |
| Type | string | No | インストール方式（Zip/Msi） | ValidateSet |
| LocalFile | string | No | ローカルインストールファイルパス | URLは不可 |
| Force | switch | No | 既存インストールを上書き | - |
| EnableException | switch | No | 例外を有効化 | - |
| Confirm | switch | No | 確認プロンプト表示 | SupportsShouldProcess |
| WhatIf | switch | No | 実行内容の表示のみ | SupportsShouldProcess |

### 入力データソース

- Microsoft ダウンロードサーバー: aka.ms経由でSqlPackageを取得
- ローカルファイル: LocalFileパラメータで指定されたZIPまたはMSIファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 実行ファイル名（sqlpackage/SqlPackage.exe） |
| Path | string | インストール先フルパス |
| Installed | bool | インストール成功フラグ（常にtrue） |
| Notes | string | 補足情報（既存インストールスキップ時のみ） |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. 既存インストールの確認
   └─ Get-DbaSqlPackagePathで確認、Force未指定で存在時はスキップ
2. プラットフォーム検証
   └─ Unix環境ではMSI不可、AllUsers不可
3. 権限検証
   └─ MSI/AllUsers時は管理者権限チェック
4. インストールパスの決定
   └─ 未指定時はスコープとプラットフォームに応じたデフォルト
5. ダウンロードURLの決定
   └─ プラットフォームとTypeに応じて選択
6. ダウンロード実行
   └─ Invoke-TlsWebRequestでダウンロード
7. インストール実行
   └─ ZIP: Expand-Archive / MSI: msiexec
8. 実行権限設定（Unix）
   └─ chmod +x実行
9. 検証と結果出力
   └─ インストール先の存在確認、結果オブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Get-DbaSqlPackagePathで既存確認]
    B --> C{既存インストール<br>あり?}
    C -->|Yes| D{Force指定?}
    D -->|No| E[スキップして結果返却]
    D -->|Yes| F[プラットフォーム検証]
    C -->|No| F
    F --> G{Unix環境?}
    G -->|Yes| H{MSI or<br>AllUsers?}
    H -->|Yes| I[エラー終了]
    H -->|No| J[権限不要で続行]
    G -->|No| K{MSI or<br>AllUsers?}
    K -->|Yes| L[管理者権限チェック]
    K -->|No| J
    L --> M{管理者権限<br>あり?}
    M -->|No| I
    M -->|Yes| J
    J --> N[インストールパス決定]
    N --> O[ダウンロードURL決定]
    O --> P{ローカルファイル<br>存在?}
    P -->|No| Q[Invoke-TlsWebRequestで<br>ダウンロード]
    P -->|Yes| R[ローカルファイル使用]
    Q --> R
    R --> S{Type=MSI?}
    S -->|Yes| T[msiexec実行]
    S -->|No| U[Expand-Archive実行]
    T --> V[インストール検証]
    U --> W{Unix環境?}
    W -->|Yes| X[chmod +x実行]
    W -->|No| V
    X --> V
    V --> Y{成功?}
    Y -->|Yes| Z[結果オブジェクト出力]
    Y -->|No| AA[エラー終了]
    Z --> AB[終了]
    AA --> AB
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-322-01 | プラットフォーム制約 | UnixではMSI/AllUsers不可 | Unix環境検出時 |
| BR-322-02 | 権限制約 | MSI/AllUsersは管理者権限必須 | Windows環境で該当スコープ/Type時 |
| BR-322-03 | スコープとType組み合わせ | MSIはAllUsersスコープ専用 | MSI選択時 |
| BR-322-04 | デフォルトインストール先 | CurrentUser: dbatools data dir / AllUsers: ProgramFiles | Path未指定時 |
| BR-322-05 | 既存インストールスキップ | Force未指定で既存あれば何もしない | 既存確認成功時 |

### 計算ロジック

インストール先パス決定ロジック：
- Path指定あり: 指定パスを使用
- CurrentUser + ZIP: `{dbatoolsData}/sqlpackage`
- AllUsers + Windows: `{ProgramFiles}\Microsoft SQL Server\DAC\bin`
- AllUsers + Unix: `/usr/local/sqlpackage`

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

本機能はデータベース操作を行わない。ファイルシステム操作のみ。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ValidationError | LocalFileがURLの場合 | Stop-Functionでエラー出力 |
| - | PlatformError | UnixでMSI/AllUsers指定 | Stop-Functionでエラー出力 |
| - | PermissionError | 管理者権限不足 | Stop-Functionでエラー出力 |
| - | DownloadError | ダウンロード失敗 | プロキシ設定でリトライ、失敗時Stop-Function |
| - | InstallError | MSIインストール失敗 | 終了コード確認、Stop-Function |
| - | ExtractError | ZIP展開失敗 | Stop-Functionでエラー出力 |

### リトライ仕様

ダウンロード時にプロキシ設定によるリトライを実施（223-229行目）。デフォルトネットワーク資格情報を使用してリトライ。

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

ファイルシステム操作のため、トランザクション制御なし。失敗時は部分的なファイルが残る可能性がある。

## パフォーマンス要件

特に定義されていない。ネットワーク状況によりダウンロード時間が変動する。進捗表示（Write-Progress）でユーザーに進行状況を通知。

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

- TLS対応のダウンロード（Invoke-TlsWebRequest使用）
- 管理者権限チェックによる不正インストール防止
- Unix環境での適切な実行権限設定（chmod +x）
- プロキシ認証対応

## 備考

- SqlPackage公式ドキュメント: Microsoft Docs
- 対応プラットフォーム: Windows, Linux, macOS
- 作者: Chrissy LeMaire and Claude

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を把握することから始める。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | 128-134行目、332-336行目のPSCustomObject定義 |

**読解のコツ**: 既存インストール時とインストール成功時で異なるプロパティセット（Notesの有無）を確認。

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

パラメータ定義と処理開始部分を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | 100-110行目のparam定義 |

**主要処理フロー**:
1. **100-110行目**: パラメータ定義（Scope=CurrentUser、Type=Zip がデフォルト）
2. **112-135行目**: 既存インストールチェック
3. **137-171行目**: プラットフォームと権限検証

#### Step 3: プラットフォーム分岐を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | 140-171行目のプラットフォーム検証 |
| 3-2 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | 194-210行目のURL決定ロジック |

**主要処理フロー**:
- **140-151行目**: Unix環境の制約チェック（MSI/AllUsers不可）
- **152-170行目**: Windows環境の権限チェック
- **194-210行目**: プラットフォーム別ダウンロードURL決定

#### Step 4: インストール処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | 241-297行目のインストールロジック |

**主要処理フロー**:
- **248-265行目**: MSIインストール（msiexec実行）
- **266-296行目**: ZIPインストール（Expand-Archive + chmod）

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

```
Install-DbaSqlPackage
    │
    ├─ Get-DbaSqlPackagePath
    │      └─ 既存インストールパスの検出
    │
    ├─ Test-ElevationRequirement
    │      └─ 管理者権限チェック
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ dbatools設定からデータディレクトリ取得
    │
    ├─ Invoke-TlsWebRequest
    │      └─ TLS対応ダウンロード
    │
    ├─ Expand-Archive
    │      └─ ZIPファイル展開
    │
    └─ Start-Process (msiexec)
           └─ MSIインストーラー実行
```

### データフロー図

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

Microsoft Download ───▶ Invoke-TlsWebRequest ───▶ 一時ファイル
       or                      │
ローカルファイル               │
                               ▼
                   ┌──────────────────────┐
                   │  Type判定           │
                   └──────────────────────┘
                        │          │
                       ZIP        MSI
                        │          │
                        ▼          ▼
              Expand-Archive    msiexec
                        │          │
                        └────┬─────┘
                             ▼
                    SqlPackage実行ファイル
                             │
                             ▼
                       PSCustomObject
                    （インストール結果）
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Install-DbaSqlPackage.ps1 | `public/Install-DbaSqlPackage.ps1` | ソース | メイン関数の実装 |
| Get-DbaSqlPackagePath.ps1 | `private/functions/Get-DbaSqlPackagePath.ps1` | ソース | 既存インストールパス検出 |
| Invoke-TlsWebRequest.ps1 | `private/functions/Invoke-TlsWebRequest.ps1` | ソース | TLS対応ダウンロード |
