# 画面設計書 269-Azure SQL Tips

## 概要

本ドキュメントは、dbatoolsのAzure SQLパフォーマンス推奨機能に関する画面設計書です。MicrosoftのAzure SQL Tipsスクリプトを実行して、Azure SQL Databaseインスタンスのパフォーマンス最適化の機会と設計推奨事項を特定するPowerShellコマンドを定義します。

### 本画面の処理概要

本機能は、Azure SQL Product Management チームが開発したget-sqldb-tips.sqlスクリプトをAzure SQL Databaseに対して実行し、データベース構成、クエリパターン、リソース使用率を分析して実用的な改善提案を提供するInvoke-DbaDbAzSqlTipコマンドを提供します。

**業務上の目的・背景**：Azure SQL Databaseのパフォーマンスチューニングには、データベース設定、インデックス使用状況、クエリパフォーマンスメトリクス、構成パラメータなど多岐にわたる分析が必要です。本機能は、Microsoftの公式推奨スクリプトを利用して、信頼度パーセンテージ付きの改善提案を自動生成し、パフォーマンス最適化を効率化します。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスします。
```powershell
Invoke-DbaDbAzSqlTip -SqlInstance <インスタンス名.database.windows.net> -SqlCredential (Get-Credential) -Database <データベース名>
```

**主要な操作・処理内容**：
1. Azure SQL Databaseインスタンスへの接続
2. Microsoft GitHubリポジトリからTipsスクリプトをダウンロード（またはローカルファイルを使用）
3. 各データベースに対してTipsクエリを実行
4. パフォーマンス推奨事項を信頼度レベル付きで出力

**画面遷移**：
- `Connect-DbaInstance`で接続を確立後に実行可能
- 単独で使用するコマンド（パイプライン入力には非対応）
- 取得結果は他の処理にパイプライン出力可能

**権限による表示制御**：
- Azure SQL Databaseへの接続権限が必要
- データベースのパフォーマンスメトリクス参照権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 411 | Invoke-DbaDbAzSqlTip | 主機能 | Azure SQLパフォーマンスTipsの実行 |

## 画面種別

CLI（コマンドラインインターフェース）- PowerShellコマンド

## URL/ルーティング

PowerShellコマンド: `Invoke-DbaDbAzSqlTip`

## 入出力項目

### パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象Azure SQLインスタンス（パイプライン入力対応） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| AzureDomain | string | No | Azure SQLドメイン（デフォルト: database.windows.net） |
| Tenant | string | No | Azure ADテナントID |
| LocalFile | string | No | ローカルTipsスクリプトのパス |
| Database | string[] | No | 対象データベース（-Database、-ExcludeDatabase、-AllUserDatabasesのいずれか必須） |
| ExcludeDatabase | string[] | No | 除外するデータベース |
| AllUserDatabases | switch | No | 全ユーザーデータベースを分析 |
| ReturnAllTips | switch | No | 全Tipsを返す（現在の状態に関係なく） |
| Compat100 | switch | No | 互換性レベル100用スクリプトを使用 |
| StatementTimeout | int | No | クエリタイムアウト（分） |
| EnableException | switch | No | 例外を有効化 |
| Force | switch | No | スクリプトの強制再ダウンロード |

## 表示項目

### 出力オブジェクト（PSCustomObject）

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | Azure SQLインスタンスのコンピュータ名 |
| InstanceName | string | Azure SQLインスタンス名 |
| SqlInstance | string | 完全なインスタンス名（例: servername.database.windows.net） |
| Database | string | 分析対象のデータベース名 |
| tip_id | int | パフォーマンス推奨の一意識別子 |
| description | string | 推奨されるパフォーマンス最適化の説明 |
| confidence_percent | int | 推奨の信頼度レベル（0-100%） |
| additional_info_url | string | 詳細ドキュメントへのURL |
| details | string | Tip固有の追加コンテキストや詳細説明 |

## イベント仕様

### 1-前処理（beginブロック）

1. -Database、-ExcludeDatabase、-AllUserDatabasesのいずれも指定されていない場合はエラー終了
2. ローカルキャッシュの確認とスクリプトダウンロード:
   - Save-DbaCommunitySoftware -Software AzSqlTips を使用
   - -Forceまたは-LocalFile指定時、またはキャッシュがない場合にダウンロード
3. Tipsクエリの読み込み:
   - Compat100指定時: get-sqldb-tips-compat-level-100-only.sql
   - 通常: get-sqldb-tips.sql
4. ReturnAllTips指定時はクエリ内の変数を1に置換

### 2-メイン処理（processブロック）

1. 各SqlInstanceに対してConnect-DbaInstanceで接続
2. Azure SQL Database以外の場合はエラー出力して次のインスタンスへ
3. AllUserDatabases指定時はMasterを除く全データベースを取得
4. 各データベースに対してInvoke-DbaQueryでTipsクエリを実行
5. 結果をPSCustomObjectとして出力

### 3-接続処理の詳細

```powershell
$connSplat = @{
    SqlInstance      = $instance
    SqlCredential    = $SqlCredential
    StatementTimeout = ($StatementTimeout * 60)
    AzureDomain      = $AzureDomain
    Tenant           = $Tenant
}
$connection = Connect-DbaInstance @connSplat

if ($connection.DatabaseEngineType -ne 'SqlAzureDatabase') {
    Stop-Function -Message '...' -Continue
}
```

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbAzSqlTip | 各種DMV | SELECT | パフォーマンスメトリクスの取得 |

本コマンドはMicrosoftの公式Tipsスクリプトを実行し、DMVやカタログビューからパフォーマンスデータを読み取ります。データベースの変更は行いません。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|--------------|---------|
| MSG001 | エラー | You must specify databases to execute against using either -Database, -ExcludeDatabase or -AllUserDatabases | データベース指定なし |
| MSG002 | エラー | Failed to update local cached copy | スクリプトダウンロード失敗 |
| MSG003 | エラー | {instance} is not an Azure SQL Database - this function only works against Azure SQL Databases | Azure SQL以外への接続 |
| MSG004 | 警告 | Could not connect at instance level... | インスタンスレベル接続失敗 |
| MSG005 | エラー | Failed to run AzSqlTips against Instance. | クエリ実行失敗 |
| MSG006 | 情報 | Connecting to {instance} | 接続開始 |
| MSG007 | 情報 | Running Azure SQL Tips against {db} | Tips実行開始 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| データベース指定なし | Stop-Functionでエラーメッセージを出力して終了 |
| スクリプトダウンロード失敗 | Stop-Functionでエラーメッセージを出力 |
| Azure SQL以外への接続 | Stop-Functionでエラーメッセージを出力してスキップ |
| インスタンスレベル接続失敗 | 警告を出力し、データベースレベルでの接続を試行 |
| クエリ実行失敗 | Stop-Functionでエラーメッセージを出力してスキップ |

## 備考

- Azure SQL Databaseのみに対応（オンプレミスSQL Serverは非対応）
- TipsスクリプトはMicrosoft GitHubリポジトリ（https://github.com/microsoft/azure-sql-tips）から自動ダウンロード
- ローカルキャッシュはPath.DbatoolsData配下のAzSqlTipsフォルダに保存
- -LocalFileでカスタマイズしたスクリプトやオフライン環境でも使用可能
- -Compat100で互換性レベル100（SQL Server 2008相当）のデータベースに対応
- Azure Government (.usgovcloudapi.net)やAzure China (.chinacloudapi.cn)にも対応

---

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

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

### 推奨読解順序

#### Step 1: 前処理を理解する

beginブロックでのスクリプト準備処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbAzSqlTip.ps1 | `public/Invoke-DbaDbAzSqlTip.ps1` | 行153-186のbeginブロック |

**読解のコツ**:
- 行156-159: データベース指定の必須チェック
- 行162-172: ローカルキャッシュの確認とダウンロード処理
- 行175-179: Compat100による分岐とクエリ読み込み
- 行181-184: ReturnAllTips変数の置換処理

#### Step 2: メイン処理を理解する

processブロックでの接続とクエリ実行処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbAzSqlTip.ps1 | `public/Invoke-DbaDbAzSqlTip.ps1` | 行188-251のprocessブロック |

**主要処理フロー**:
1. **189-220行**: インスタンスへの接続と検証
2. **193-200行**: Connect-DbaInstanceのスプラット構築
3. **202-204行**: Azure SQL Database以外の検出とエラー処理
4. **206-208行**: AllUserDatabases時のデータベースリスト取得
5. **222-249行**: 各データベースへのクエリ実行ループ

#### Step 3: 出力形式を理解する

PSCustomObjectの構築を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbAzSqlTip.ps1 | `public/Invoke-DbaDbAzSqlTip.ps1` | 行233-245の出力オブジェクト構築 |

**出力プロパティ**:
```powershell
[PSCustomObject]@{
    ComputerName        = $connection.ComputerName
    InstanceName        = $connection.Name
    SqlInstance         = $connection.DomainInstanceName
    Database            = $db
    tip_id              = $PSItem.tip_id
    description         = $PSItem.description
    confidence_percent  = $PSItem.confidence_percent
    additional_info_url = $PSItem.additional_info_url
    details             = $PSItem.details
}
```

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

```
Invoke-DbaDbAzSqlTip
    |
    +-- begin block
    |       |
    |       +-- パラメータ検証（Database/ExcludeDatabase/AllUserDatabases）
    |       |       |
    |       |       +-- 未指定時: Stop-Function
    |       |
    |       +-- Get-DbatoolsConfigValue -FullName 'Path.DbatoolsData'
    |       |
    |       +-- Save-DbaCommunitySoftware -Software AzSqlTips
    |       |       |
    |       |       +-- ローカルキャッシュの更新
    |       |
    |       +-- Get-Content (Tipsクエリ読み込み)
    |               |
    |               +-- Compat100分岐
    |               +-- ReturnAllTips変数置換
    |
    +-- process block
            |
            +-- foreach ($instance in $SqlInstance)
                    |
                    +-- Connect-DbaInstance
                    |       |
                    |       +-- AzureDomain, Tenant, SqlCredential指定
                    |
                    +-- DatabaseEngineType チェック
                    |       |
                    |       +-- SqlAzureDatabase以外: エラー
                    |
                    +-- AllUserDatabases 処理
                    |       |
                    |       +-- $connection.Databases でDBリスト取得
                    |
                    +-- foreach ($db in $Database)
                            |
                            +-- Invoke-DbaQuery -Query $azTipsQuery
                                    |
                                    +-- ForEach-Object
                                            |
                                            +-- PSCustomObject 出力
```

### データフロー図

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

SqlInstance/         +------------------+
SqlCredential    -->| begin block      |
AzureDomain/         | パラメータ検証   |
Tenant               +--------+---------+
                              |
                              v
LocalFile/           +------------------+
Force            -->| Save-DbaCommunit |
                     | ySoftware        |
                     | (スクリプト取得) |
                     +--------+---------+
                              |
                              v
Compat100/           +------------------+
ReturnAllTips    -->| クエリ読み込み    |
                     | & 変数置換       |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | Connect-DbaInst  |
                     | ance             |
                     +--------+---------+
                              |
                              v
Database/            +------------------+
ExcludeDatabase/ -->| データベース     |
AllUserDatabases     | リスト取得       |
                     +--------+---------+
                              |
                              v
                     +------------------+
                     | Invoke-DbaQuery  |---> PSCustomObject[]
                     | (Tips実行)       |     (tip_id, description,
                     +------------------+      confidence_percent等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbAzSqlTip.ps1 | `public/Invoke-DbaDbAzSqlTip.ps1` | ソース | Azure SQL Tips実行の主要ロジック |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 依存 | Azure SQL接続 |
| Invoke-DbaQuery.ps1 | `public/Invoke-DbaQuery.ps1` | 依存 | クエリ実行 |
| Save-DbaCommunitySoftware.ps1 | `public/Save-DbaCommunitySoftware.ps1` | 依存 | Tipsスクリプトのダウンロード |
| get-sqldb-tips.sql | (外部) | 外部 | Microsoft Azure SQL Tipsスクリプト |
