# 機能設計書 172-Invoke-DbaDbUpgrade

## 概要

本ドキュメントは、dbatools PowerShellモジュールのInvoke-DbaDbUpgrade関数の機能設計を定義する。データベースの互換性レベルをアップグレードし、ポストアップグレードのメンテナンスタスクを実行する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのアップグレードまたはデータベースの新しいインスタンスへの移行後に必要な重要なステップを自動化する。DBAが通常手動で行うアップグレード後のチェックリスト（互換性レベル更新、DBCC CHECKDB、DBCC UPDATEUSAGE、統計更新、ビューリフレッシュ）を一括で実行し、データベースが新バージョンで最適に機能することを確保する。

**機能の利用シーン**：
- SQL Serverのメジャーバージョンアップグレード後のデータベース最適化
- データベースを新しいSQL Serverインスタンスに移行した後のメンテナンス
- インスタンス全体の互換性レベル標準化
- 定期的なデータベース整合性チェックとメンテナンス

**主要な処理内容**：
1. データベースの互換性レベルをホストSQL Serverバージョンに更新
2. SQL Server 2016以降の場合、ターゲットリカバリタイムを60秒に設定
3. DBCC CHECKDB DATA_PURITYを実行してデータ破損を検出
4. DBCC UPDATEUSAGEを実行してページカウントの不正を修正
5. sp_updatestatsを実行して統計を更新
6. sp_refreshviewを実行して全ユーザービューのメタデータを更新

**関連システム・外部連携**：SQL Server Management Objects (SMO) を使用してデータベースプロパティを変更。T-SQLコマンド（DBCC、ストアドプロシージャ）を直接実行。

**権限による制御**：データベースの互換性レベル変更にはALTER DATABASE権限が必要。DBCCコマンドにはsysadminまたはdb_owner権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 56 | データベースアップグレード | 主機能 | データベースのアップグレード |

## 機能種別

データベースメンテナンス / アップグレード処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | ターゲットSQL Serverインスタンス | Position 0 |
| SqlCredential | PSCredential | No | 接続資格情報 | - |
| Database | object[] | No | アップグレード対象データベース | ワイルドカード対応 |
| ExcludeDatabase | object[] | No | 除外するデータベース | ワイルドカード対応 |
| AllUserDatabases | switch | No | 全ユーザーデータベースを処理 | - |
| Force | switch | No | 互換性レベルが正しくても全タスク実行 | - |
| NoCheckDb | switch | No | DBCC CHECKDBをスキップ | - |
| NoUpdateUsage | switch | No | DBCC UPDATEUSAGEをスキップ | - |
| NoUpdateStats | switch | No | sp_updatestatsをスキップ | - |
| NoRefreshView | switch | No | sp_refreshviewをスキップ | - |
| InputObject | Database[] | No | パイプラインからのデータベースオブジェクト | ValueFromPipeline |
| EnableException | switch | No | 例外をスローするか | - |

### 入力データソース

- SqlInstanceパラメータで指定されたSQL Serverインスタンス
- Get-DbaDatabase等からパイプラインで渡されるデータベースオブジェクト

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | アップグレードされたデータベース名 |
| OriginalCompatibility | string | 元の互換性レベル |
| CurrentCompatibility | string | 新しい互換性レベル |
| Compatibility | string | 互換性更新結果（バージョン番号/No change/Fail） |
| TargetRecoveryTime | string | ターゲットリカバリタイム更新結果（60/No change/Fail） |
| DataPurity | string | CHECKDB結果（Success/Fail） |
| UpdateUsage | string | UPDATEUSAGE結果（Success/Fail/Skipped） |
| UpdateStats | string | sp_updatestats結果（Success/Fail/Skipped） |
| RefreshViews | string | sp_refreshview結果（Success/Fail/Skipped） |

### 出力先

- 標準出力（パイプライン）にPSCustomObjectを出力

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   ├─ SqlInstanceまたはInputObjectの指定確認
   └─ Database/ExcludeDatabase/AllUserDatabasesの指定確認

2. インスタンスへの接続
   └─ Connect-DbaInstanceで接続確立

3. データベースフィルタリング
   ├─ システムデータベースを除外
   ├─ Databaseパラメータでフィルタ
   └─ ExcludeDatabaseパラメータで除外

4. 各データベースに対する処理
   ├─ 4.1 現在の互換性レベルとターゲットリカバリタイム確認
   ├─ 4.2 Force未指定で両方OKならスキップ
   ├─ 4.3 互換性レベルの更新（必要時）
   ├─ 4.4 ターゲットリカバリタイムの更新（SQL 2016+、必要時）
   ├─ 4.5 DBCC CHECKDB DATA_PURITY実行（NoCheckDb未指定時）
   ├─ 4.6 DBCC UPDATEUSAGE実行（NoUpdateUsage未指定時）
   ├─ 4.7 sp_updatestats実行（NoUpdateStats未指定時）
   └─ 4.8 sp_refreshview実行（NoRefreshView未指定時）

5. 結果オブジェクト出力
   └─ PSCustomObjectとしてパイプライン出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{パラメータ検証}
    B -->|Invalid| Z[警告出力・終了]
    B -->|Valid| C[Connect-DbaInstance]
    C --> D[データベースフィルタリング]
    D --> E{データベースループ}
    E -->|次のDB| F[現在の設定確認]
    F --> G{Force指定 or<br/>設定が必要?}
    G -->|No| E
    G -->|Yes| H[互換性レベル更新]
    H --> I{SQL 2016+?}
    I -->|Yes| J[TargetRecoveryTime更新]
    I -->|No| K{NoCheckDb?}
    J --> K
    K -->|No| L[DBCC CHECKDB]
    K -->|Yes| M{NoUpdateUsage?}
    L --> M
    M -->|No| N[DBCC UPDATEUSAGE]
    M -->|Yes| O{NoUpdateStats?}
    N --> O
    O -->|No| P[sp_updatestats]
    O -->|Yes| Q{NoRefreshView?}
    P --> Q
    Q -->|No| R[sp_refreshview]
    Q -->|Yes| S[結果オブジェクト出力]
    R --> S
    S --> E
    E -->|完了| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-172-01 | 互換性レベル自動設定 | 互換性レベルはホストSQL Serverのバージョンに合わせて設定 | 常時 |
| BR-172-02 | ターゲットリカバリタイム | SQL Server 2016以降ではターゲットリカバリタイムを60秒に設定 | SQL Server 2016+ |
| BR-172-03 | Forceモード | 設定が正しくても全メンテナンスタスクを実行 | Force指定時 |
| BR-172-04 | スキップ判定 | Force未指定で互換性レベルとターゲットリカバリタイムが正しい場合はスキップ | Force未指定時 |

### 計算ロジック

- 互換性レベル: `[Microsoft.SqlServer.Management.Smo.CompatibilityLevel]"Version$($serverVersion)0"`
- SQL Server 2016判定: `$serverVersion -ge 13`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 互換性レベル更新 | sys.databases | UPDATE | データベースの互換性レベルを変更 |
| TargetRecoveryTime更新 | sys.databases | UPDATE | ターゲットリカバリタイムを変更 |
| DBCC CHECKDB | 全テーブル | SELECT | データ整合性チェック |
| DBCC UPDATEUSAGE | sysindexes | UPDATE | ページカウント修正 |
| sp_updatestats | 統計オブジェクト | UPDATE | 統計情報更新 |
| sp_refreshview | sys.objects | UPDATE | ビューメタデータ更新 |

### テーブル別操作詳細

#### DBCC CHECKDB DATA_PURITY
```sql
DBCC CHECKDB ('DatabaseName') WITH DATA_PURITY, NO_INFOMSGS
```

#### DBCC UPDATEUSAGE
```sql
DBCC UPDATEUSAGE (DatabaseName) WITH NO_INFOMSGS;
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | インスタンスへの接続失敗 | 接続情報を確認 |
| - | CompatibilityError | 互換性レベル更新失敗 | 権限を確認 |
| - | CheckDbError | DBCC CHECKDB失敗 | データベース整合性を確認 |
| - | UpdateUsageError | DBCC UPDATEUSAGE失敗 | 権限を確認 |
| - | UpdateStatsError | sp_updatestats失敗 | 権限を確認 |
| - | RefreshViewError | sp_refreshview失敗 | ビュー定義を確認 |

### リトライ仕様

リトライ機能は実装されていない。各ステップでエラーが発生した場合、Failステータスを設定して次のステップに進む。

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

各DBCCコマンドとストアドプロシージャは独立して実行される。一部が失敗しても他のステップは継続実行される。

## パフォーマンス要件

- DBCC CHECKDBは大規模データベースで時間がかかる可能性がある
- NoCheckDbオプションで時間短縮可能
- 大量のビューがある場合、RefreshViewに時間がかかる可能性がある

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

- ALTER DATABASE権限が必要
- sysadminまたはdb_owner権限が推奨
- SqlCredentialによる安全な認証をサポート

## 備考

- Thomas LaRockのSQL Serverアップグレードチェックリストに基づく実装
- 参考: https://thomaslarock.com/2014/06/upgrading-to-sql-server-2014-a-dozen-things-to-check/

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造と各プロパティの意味を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | 309-322行目: 出力PSCustomObjectの構造 |

**読解のコツ**: 各プロパティ（Compatibility, TargetRecoveryTime, DataPurity等）が何を表すか理解する。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | 関数全体の流れを把握 |

**主要処理フロー**:
1. **148-150行目**: beginブロックでForce時のConfirmPreference設定
2. **151-170行目**: パラメータ検証とインスタンス接続
3. **172-178行目**: データベースフィルタリング
4. **180-197行目**: 互換性レベルとターゲットリカバリタイム判定
5. **199-229行目**: 互換性レベルとターゲットリカバリタイムの更新
6. **231-262行目**: DBCC CHECKDBとUPDATEUSAGE実行
7. **264-304行目**: sp_updatestatsとsp_refreshview実行

#### Step 3: 各メンテナンス処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | 231-245行目: DBCC CHECKDB処理 |
| 3-2 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | 247-262行目: DBCC UPDATEUSAGE処理 |
| 3-3 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | 264-279行目: sp_updatestats処理 |
| 3-4 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | 281-304行目: sp_refreshview処理 |

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

```
Invoke-DbaDbUpgrade
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ db.CompatibilityLevel (SMO)
    │      └─ 互換性レベル設定
    │
    ├─ db.TargetRecoveryTime (SMO)
    │      └─ ターゲットリカバリタイム設定
    │
    ├─ db.ExecuteNonQuery("DBCC CHECKDB...")
    │
    ├─ db.ExecuteNonQuery("DBCC UPDATEUSAGE...")
    │
    ├─ db.ExecuteNonQuery("EXEC sp_updatestats")
    │
    └─ db.ExecuteNonQuery("EXECUTE sp_refreshview...")
           └─ 各ビューに対して実行
```

### データフロー図

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

SqlInstance ──────┐
Database ─────────┼──▶ Connect-DbaInstance ──▶ Server Object
ExcludeDatabase ──┘              │
                                 ▼
InputObject ──────────▶ データベースフィルタリング
                                 │
                                 ▼
                         ┌───────┴───────┐
                         ▼               ▼
                   [互換性レベル]  [ターゲットリカバリ]
                         │               │
                         ▼               ▼
                   ┌─────┴─────┬─────────┘
                   ▼           ▼
              DBCC CHECKDB  DBCC UPDATEUSAGE
                   │           │
                   ▼           ▼
             sp_updatestats  sp_refreshview
                   │           │
                   └─────┬─────┘
                         ▼
                   PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | ソース | メイン関数 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得（パイプライン入力元） |
