# 機能設計書 164-Invoke-DbaDbAzSqlTip

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Invoke-DbaDbAzSqlTip`コマンドレットに関する機能設計書である。このコマンドは、MicrosoftのAzure SQLパフォーマンス推奨スクリプトをAzure SQL Databaseインスタンスに対して実行する機能を提供する。

### 本機能の処理概要

Invoke-DbaDbAzSqlTipは、Azure SQL Databaseインスタンスに対してMicrosoftのAzure SQL Tipsスクリプト（get-sqldb-tips.sql）を実行し、パフォーマンス最適化の機会と設計推奨事項を特定する。このスクリプトはAzure SQL製品管理チームによって開発され、データベース構成、クエリパターン、リソース使用率を分析して、実行可能な改善提案を信頼度パーセンテージ付きで提供する。

**業務上の目的・背景**：
Azure SQL Databaseを使用する組織では、パフォーマンスの最適化とコスト効率の向上が常に求められる。このコマンドは、Microsoftの公式推奨事項に基づいた自動化されたパフォーマンス分析を提供し、DBAがデータベースの設計や構成の問題を迅速に特定できるようにする。手動での分析に比べて大幅な時間短縮が可能。

**機能の利用シーン**：
- Azure SQL Databaseの定期的なパフォーマンス監査
- 本番環境デプロイ前の構成レビュー
- パフォーマンス問題のトラブルシューティング
- コスト最適化のための分析
- 新規Azure SQLデータベースのベストプラクティス検証

**主要な処理内容**：
1. Azure SQL Tipsスクリプトのローカルキャッシュ確認/ダウンロード
2. Azure SQL Databaseへの接続
3. 対象データベースの決定（Database、ExcludeDatabase、AllUserDatabases）
4. Azure SQL Tipsクエリの実行
5. 推奨事項の結果オブジェクト生成と返却

**関連システム・外部連携**：
- GitHub（https://github.com/microsoft/azure-sql-tips）からのスクリプトダウンロード
- Azure SQL Database
- Azure Active Directory認証

**権限による制御**：
- Azure SQL Databaseへの接続権限が必要
- 分析に必要なDMV（動的管理ビュー）へのアクセス権限が必要

## 関連画面

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

## 機能種別

分析処理 / パフォーマンス診断

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | ターゲットのAzure SQLインスタンス | パイプライン入力対応 |
| SqlCredential | PSCredential | No | 代替資格情報 | - |
| AzureDomain | string | No | Azure SQLドメイン（デフォルト: database.windows.net） | - |
| Tenant | string | No | Azure ADテナントID（GUID） | - |
| LocalFile | string | No | ローカルのAzure SQL Tipsスクリプトファイルパス | ValidateScript: Test-Path |
| Database | string[] | No | 分析対象データベース | - |
| ExcludeDatabase | string[] | No | 除外するデータベース | - |
| AllUserDatabases | switch | No | 全ユーザーデータベースを対象 | - |
| ReturnAllTips | switch | No | 現在の状態に関わらず全推奨事項を返す | - |
| Compat100 | switch | No | 互換性レベル100（SQL Server 2008）用スクリプトを使用 | - |
| StatementTimeout | int | No | クエリタイムアウト（分） | - |
| EnableException | switch | No | 例外を有効化 | - |
| Force | switch | No | GitHubから強制的に再ダウンロード | - |

### 入力データソース

- コマンドライン引数
- ローカルキャッシュまたはGitHubからのAzure SQL Tipsスクリプト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | Azure SQLインスタンスのコンピュータ名 |
| InstanceName | string | Azure SQLインスタンス名 |
| SqlInstance | string | 完全なAzure SQLインスタンス名（servername.database.windows.net） |
| Database | string | 分析されたデータベースの名前 |
| tip_id | int | パフォーマンス推奨事項の一意識別子 |
| description | string | 推奨されているパフォーマンス最適化のテキスト説明 |
| confidence_percent | int | 推奨事項が分析されたデータベースに適用可能である信頼度レベル（0-100） |
| additional_info_url | string | 推奨事項の詳細を説明するMicrosoftドキュメントまたは追加リソースへのURL |
| details | string | 推奨事項に固有の追加コンテキストまたは詳細説明 |

### 出力先

コンソール（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. beginブロック
   ├─ データベース指定パラメータの検証
   │   └─ Database、ExcludeDatabase、AllUserDatabasesのいずれかが必須
   ├─ ローカルキャッシュの確認
   │   ├─ Force指定またはキャッシュなし: Save-DbaCommunitySoftware実行
   │   └─ キャッシュあり: キャッシュ使用
   └─ Azure SQL Tipsクエリの読み込み
       ├─ Compat100: get-sqldb-tips-compat-level-100-only.sql
       └─ 通常: get-sqldb-tips.sql
2. processブロック
   ├─ SqlInstanceのループ処理
   │   ├─ Connect-DbaInstance（AzureDomain、Tenant指定可）
   │   ├─ DatabaseEngineType検証（SqlAzureDatabaseのみ）
   │   └─ AllUserDatabases時: データベース一覧取得
   └─ 各データベースのループ処理
       ├─ Invoke-DbaQueryでAzure SQL Tipsクエリ実行
       └─ 結果オブジェクトの生成
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Database/ExcludeDatabase/AllUserDatabases指定あり?}
    B -->|No| C[Stop-Function エラー終了]
    B -->|Yes| D{ローカルキャッシュあり?}

    D -->|No or Force| E[Save-DbaCommunitySoftware]
    D -->|Yes| F[キャッシュ使用]

    E --> G{Compat100?}
    F --> G

    G -->|Yes| H[get-sqldb-tips-compat-level-100-only.sql読み込み]
    G -->|No| I[get-sqldb-tips.sql読み込み]

    H --> J{ReturnAllTips?}
    I --> J

    J -->|Yes| K[ReturnAllTips変数を1に設定]
    J -->|No| L[SqlInstanceループ開始]
    K --> L

    L --> M[Connect-DbaInstance]
    M --> N{Azure SQL Database?}
    N -->|No| O[Stop-Function Continue]
    N -->|Yes| P{AllUserDatabases?}

    O --> L
    P -->|Yes| Q[データベース一覧取得]
    P -->|No| R[指定Databaseを使用]

    Q --> S[Databaseループ開始]
    R --> S

    S --> T[Invoke-DbaQuery実行]
    T --> U[結果オブジェクト生成]
    U --> V{次のDatabase?}
    V -->|Yes| S
    V -->|No| W{次のSqlInstance?}
    W -->|Yes| L
    W -->|No| X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | データベース指定必須 | Database、ExcludeDatabase、AllUserDatabasesのいずれかが必須 | 常時 |
| BR-002 | Azure SQL専用 | Azure SQL Databaseのみサポート（オンプレミスSQL Server非対応） | 常時 |
| BR-003 | master除外 | AllUserDatabases時はmasterデータベースを自動除外 | AllUserDatabases=true |
| BR-004 | スクリプトキャッシュ | スクリプトはローカルにキャッシュされ、Force指定で再ダウンロード | 常時 |
| BR-005 | 互換性レベル100対応 | レガシーデータベース用の専用スクリプトが存在 | Compat100=true |

### 計算ロジック

**ReturnAllTips変数の設定**:
```
ReturnAllTips=true時、スクリプト内の変数を1に置換
$azTipsQuery = ($azTipsQuery -replace '(?<=ReturnAllTips)(\D+)(\d+)', ('$1 1'))
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Azure SQL Tips実行 | 各種DMV | SELECT | パフォーマンス分析クエリの実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ParameterError | データベース指定パラメータ未指定 | Stop-Function |
| - | DownloadError | スクリプトダウンロード失敗 | Stop-Function |
| - | ConnectionError | Azure SQL Databaseへの接続失敗 | 警告メッセージ出力 |
| - | EngineTypeError | オンプレミスSQL Serverへの接続 | Stop-Function -Continue |
| - | QueryError | Azure SQL Tipsクエリ実行失敗 | Stop-Function -Continue |

### リトライ仕様

リトライ機能なし（エラー発生時は次のデータベース/インスタンスに継続）

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

該当なし（読み取り専用クエリ）

## パフォーマンス要件

- StatementTimeoutパラメータでクエリタイムアウトを分単位で指定可能
- 大規模データベースでは実行時間が長くなる可能性あり

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

- SQL Server認証およびAzure Active Directory認証をサポート
- MFAサポートにはConnect-DbaInstanceを使用
- ソブリンクラウド（Azure Government、Azure China）対応（AzureDomainパラメータ）

## 備考

- スクリプトソース: https://github.com/microsoft/azure-sql-tips
- ローカルキャッシュパス: DbatoolsData\AzSqlTips
- Azure SQL Database専用（オンプレミスSQL Server非対応）

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | 出力PSCustomObject | 234-244行目 | tip_id, description, confidence_percent, additional_info_url, details |

**読解のコツ**: 出力オブジェクトはAzure SQL Tipsクエリの結果をそのまま反映。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbAzSqlTip.ps1 | `public/Invoke-DbaDbAzSqlTip.ps1` | 関数全体の構造とパラメータ定義 |

**主要処理フロー**:
1. **134-151行目**: パラメータ定義
2. **153-186行目**: beginブロック（スクリプト準備）
3. **188-251行目**: processブロック（メイン処理）

#### Step 3: スクリプト準備処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | beginブロック | 153-186行目 | キャッシュ確認とスクリプト読み込み |

**主要処理フロー**:
- **156-159行目**: データベース指定パラメータの検証
- **161-172行目**: ローカルキャッシュの確認とダウンロード
- **174-179行目**: Compat100に応じたスクリプト選択
- **181-184行目**: ReturnAllTips変数の置換

#### Step 4: クエリ実行処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | processブロック | 188-251行目 | 接続、データベース列挙、クエリ実行 |

**主要処理フロー**:
- **189-220行目**: インスタンス接続とAzure SQL検証
- **222-249行目**: データベースループとクエリ実行
- **233-245行目**: Invoke-DbaQueryと結果オブジェクト生成

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

```
Invoke-DbaDbAzSqlTip
    │
    ├─ Get-DbatoolsConfigValue
    │      └─ Path.DbatoolsData取得
    │
    ├─ Save-DbaCommunitySoftware
    │      └─ AzSqlTipsスクリプトのダウンロード
    │
    ├─ Get-Content
    │      └─ スクリプトファイルの読み込み
    │
    ├─ Connect-DbaInstance
    │      └─ Azure SQL Database接続
    │
    └─ Invoke-DbaQuery
           └─ Azure SQL Tipsクエリ実行
```

### データフロー図

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

LocalFile ─────────────────┐
       or                  │
GitHub Download ──────────┼──▶ Azure SQL Tipsスクリプト準備
                          │
                          ▼
SqlInstance ─────────────▶ Connect-DbaInstance
SqlCredential ───────────▶ (Azure AD/SQL認証)
AzureDomain ─────────────▶
Tenant ──────────────────▶
                               │
                               ▼
Database ────────────────▶ データベース決定
ExcludeDatabase ─────────▶
AllUserDatabases ────────▶
                               │
                               ▼
ReturnAllTips ───────────▶ スクリプト変数調整
Compat100 ───────────────▶
                               │
                               ▼
                         Invoke-DbaQuery
                               │
                               ▼
                         ┌────────────────────┐
                         │ PSCustomObject生成  │──────▶ コンソール出力
                         │ - tip_id           │
                         │ - description      │
                         │ - confidence_percent│
                         │ - additional_info_url│
                         │ - details          │
                         └────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbAzSqlTip.ps1 | `public/Invoke-DbaDbAzSqlTip.ps1` | ソース | メイン関数定義 |
| Save-DbaCommunitySoftware.ps1 | `public/Save-DbaCommunitySoftware.ps1` | ソース | コミュニティソフトウェアのダウンロード |
| get-sqldb-tips.sql | `DbatoolsData/AzSqlTips/sqldb-tips/` | 外部スクリプト | Azure SQL Tipsメインスクリプト |
| get-sqldb-tips-compat-level-100-only.sql | `DbatoolsData/AzSqlTips/sqldb-tips/` | 外部スクリプト | 互換性レベル100用スクリプト |
