# 画面設計書 56-データベースアップグレード

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるデータベースアップグレード機能の設計仕様を記載したものです。SQL Serverアップグレード後またはデータベース移行後に必要なポストアップグレードメンテナンスタスクを自動化する機能を提供します。

### 本画面の処理概要

本機能は、SQL Serverのバージョンアップグレードまたはデータベースの新しいインスタンスへの移行後に実行すべき重要なメンテナンスタスクを自動化するPowerShellコマンドを提供します。互換性レベルの更新、ターゲットリカバリタイム設定、DBCC CHECKDB、統計更新、ビューリフレッシュなどを一括実行します。

**業務上の目的・背景**：SQL Serverのアップグレード後、データベースは以前のバージョンの互換性レベルを維持し、新機能やオプティマイザの改善を活用できない状態になります。また、データベースのメタデータや統計情報が古くなり、パフォーマンスに影響を与える可能性があります。本機能は、DBAが手動で行うアップグレード後チェックリストを自動化し、データベースが新バージョンで最適に動作するようにします。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします:
- `Invoke-DbaDbUpgrade` - データベースのアップグレード

**主要な操作・処理内容**：
1. データベースの互換性レベルをサーバーバージョンに合わせて更新
2. ターゲットリカバリタイムを60秒に設定（SQL Server 2016以降）
3. DBCC CHECKDB WITH DATA_PURITY の実行
4. DBCC UPDATEUSAGE の実行
5. sp_updatestats の実行
6. 全ユーザービューに対するsp_refreshviewの実行

**画面遷移**：本機能はCLIコマンドであり、Get-DbaDatabase からパイプライン入力を受け取ることができます。Out-GridView等と組み合わせて対話的なデータベース選択も可能です。

**権限による表示制御**：データベースのアップグレード操作にはdb_owner権限または同等の権限が必要です。DBCC CHECKDBにはsysadmin権限が推奨されます。

## 関連機能

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

## 画面種別

実行（CLI）

## URL/ルーティング

PowerShellコマンドとして以下のコマンドレット名でアクセス:
- `Invoke-DbaDbUpgrade`

## 入出力項目

### Invoke-DbaDbUpgrade パラメータ

| パラメータ名 | 必須 | 型 | 説明 |
|-------------|------|-----|------|
| SqlInstance | No | DbaInstanceParameter[] | 対象SQL Serverインスタンス |
| SqlCredential | No | PSCredential | 認証用資格情報 |
| Database | No | object[] | 対象データベース（ワイルドカード対応） |
| ExcludeDatabase | No | object[] | 除外データベース |
| AllUserDatabases | No | switch | 全ユーザーデータベースを対象 |
| Force | No | switch | 互換性レベルが正しくてもすべてのタスクを実行 |
| NoCheckDb | No | switch | DBCC CHECKDBをスキップ |
| NoUpdateUsage | No | switch | DBCC UPDATEUSAGEをスキップ |
| NoUpdateStats | No | switch | sp_updatestatsをスキップ |
| NoRefreshView | No | switch | sp_refreshviewをスキップ |
| InputObject | No | Database[] | パイプライン入力 |
| EnableException | No | switch | 例外を有効化 |

## 表示項目

### Invoke-DbaDbUpgrade 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQLサーバーのコンピュータ名 |
| InstanceName | string | SQLサーバーインスタンス名 |
| SqlInstance | string | フルインスタンス名 |
| Database | string | データベース名 |
| OriginalCompatibility | string | アップグレード前の互換性レベル |
| CurrentCompatibility | string | アップグレード後の互換性レベル |
| Compatibility | string | 互換性レベル更新結果 |
| TargetRecoveryTime | string | ターゲットリカバリタイム更新結果 |
| DataPurity | string | DBCC CHECKDB結果 |
| UpdateUsage | string | DBCC UPDATEUSAGE結果 |
| UpdateStats | string | sp_updatestats結果 |
| RefreshViews | string | sp_refreshview結果 |

## イベント仕様

### 1-データベースアップグレード実行

1. `Connect-DbaInstance`でSQL Serverインスタンスに接続
2. 対象データベースの選択（パラメータまたはパイプライン入力）
3. システムデータベースの除外
4. 現在の互換性レベルとサーバーレベルの比較
5. 互換性レベルの更新（必要な場合）
6. ターゲットリカバリタイムの更新（SQL Server 2016以降、60秒に設定）
7. DBCC CHECKDB WITH DATA_PURITY の実行（NoCheckDb未指定時）
8. DBCC UPDATEUSAGE の実行（NoUpdateUsage未指定時）
9. sp_updatestats の実行（NoUpdateStats未指定時）
10. 各ユーザービューに対するsp_refreshviewの実行（NoRefreshView未指定時）
11. 結果オブジェクトの出力

### 2-互換性レベル更新

1. サーバーのメジャーバージョンからターゲット互換性レベルを決定
2. データベースの現在の互換性レベルと比較
3. 更新が必要な場合、$db.CompatibilityLevelプロパティを設定
4. $db.Alter()で変更を永続化

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Invoke-DbaDbUpgrade | sys.databases | UPDATE | 互換性レベル、ターゲットリカバリタイムの更新 |
| Invoke-DbaDbUpgrade | - | DBCC CHECKDB | データベース整合性チェック |
| Invoke-DbaDbUpgrade | sys.sysindexes | UPDATE | DBCC UPDATEUSAGEによる領域情報更新 |
| Invoke-DbaDbUpgrade | statistics | UPDATE | sp_updatestatsによる統計更新 |
| Invoke-DbaDbUpgrade | sys.views | UPDATE | sp_refreshviewによるビューメタデータ更新 |

### テーブル別更新項目詳細

#### sys.databases（互換性レベル更新）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | compatibility_level | サーバーバージョンに対応する値 | 100, 110, 120, 130, 140, 150, 160等 |
| UPDATE | target_recovery_time_in_seconds | 60 | SQL Server 2016以降 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|---------|
| MSG-001 | 警告 | You must specify either a SQL instance or pipe a database collection | SqlInstance/InputObject未指定 |
| MSG-002 | 警告 | You must explicitly specify a database | Database/ExcludeDatabase/AllUserDatabases/InputObject未指定 |
| MSG-003 | 警告 | Failed run Compatibility Upgrade | 互換性レベル更新失敗 |
| MSG-004 | 警告 | Failed to change target recovery time | ターゲットリカバリタイム更新失敗 |
| MSG-005 | 警告 | Failed run DBCC CHECKDB with DATA_PURITY on $db | CHECKDB失敗 |
| MSG-006 | 警告 | Failed to run DBCC UPDATEUSAGE on $db | UPDATEUSAGE失敗 |
| MSG-007 | 警告 | Failed to run sp_updatestats on $db | sp_updatestats失敗 |
| MSG-008 | 警告 | Failed update view $fullName on $db | sp_refreshview失敗 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理停止、エラーメッセージ出力 |
| 互換性レベル更新失敗 | Compatibility="Fail"を設定、処理継続 |
| ターゲットリカバリタイム更新失敗 | TargetRecoveryTime="Fail"を設定、処理継続 |
| DBCC CHECKDB失敗 | DataPurity="Fail"を設定、処理継続 |
| sp_updatestats失敗 | UpdateStats="Fail"を設定、処理継続 |
| sp_refreshview失敗 | RefreshViews="Fail"を設定（一部失敗でも処理継続） |

## 備考

- 既に正しい互換性レベルとターゲットリカバリタイムの場合、Forceオプションなしではスキップされる
- Thomas LaRock氏のSQL Server 2014アップグレードチェックリストに基づく設計
- SQL Server 2016以降ではターゲットリカバリタイムのデフォルトが60秒に変更された
- ビューのリフレッシュは各ビューで個別に実行され、一部が失敗しても他は継続

---

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

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

### 推奨読解順序

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

データベースの互換性レベルと関連プロパティを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | SMO Database.CompatibilityLevel | Microsoft.SqlServer.Management.Smo | 互換性レベルプロパティ |
| 1-2 | SMO Database.TargetRecoveryTime | Microsoft.SqlServer.Management.Smo | ターゲットリカバリタイムプロパティ |
| 1-3 | SMO CompatibilityLevel列挙型 | Microsoft.SqlServer.Management.Smo | Version100, Version110等 |

**読解のコツ**: 互換性レベルはサーバーのメジャーバージョンに10を掛けた値になります（例: SQL Server 2016 = 130）。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | アップグレード処理のメインロジック |

**主要処理フロー (Invoke-DbaDbUpgrade)**:
1. **行148-150**: begin ブロック - Force指定時のConfirmPreference設定
2. **行163-170**: データベースオブジェクトの取得
3. **行180-197**: 互換性レベルチェックと更新要否判定
4. **行199-213**: 互換性レベルの更新
5. **行215-230**: ターゲットリカバリタイムの更新
6. **行231-245**: DBCC CHECKDB DATA_PURITY実行
7. **行247-262**: DBCC UPDATEUSAGE実行
8. **行264-279**: sp_updatestats実行
9. **行281-304**: sp_refreshview実行
10. **行306-323**: 結果オブジェクト出力

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` 行234 | DBCC CHECKDB SQL |
| 3-2 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` 行250 | DBCC UPDATEUSAGE SQL |
| 3-3 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` 行267 | sp_updatestats SQL |
| 3-4 | Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` 行290 | sp_refreshview SQL |

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

```
Invoke-DbaDbUpgrade
    |
    +-- パラメータ検証
    |
    +-- Connect-DbaInstance
    |
    +-- データベース取得
    |       +-- $server.Databases | Where-Object IsAccessible
    |       +-- システムDBの除外
    |
    +-- 互換性レベルチェック
    |       +-- $db.CompatibilityLevel vs サーバーレベル
    |
    +-- 互換性レベル更新
    |       +-- $db.CompatibilityLevel = $serverLevel
    |       +-- $db.Alter()
    |
    +-- ターゲットリカバリタイム更新
    |       +-- $db.TargetRecoveryTime = 60
    |       +-- $db.Alter()
    |
    +-- DBCC CHECKDB
    |       +-- $db.ExecuteNonQuery()
    |
    +-- DBCC UPDATEUSAGE
    |       +-- $db.ExecuteNonQuery()
    |
    +-- sp_updatestats
    |       +-- $db.ExecuteNonQuery()
    |
    +-- sp_refreshview (各ビュー)
    |       +-- $db.ExecuteNonQuery()
    |
    +-- 結果出力
            +-- PSCustomObject
```

### データフロー図

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

SqlInstance/     ------>  Connect-DbaInstance
InputObject               |
                         v
Database/        ------>  データベース選択
ExcludeDatabase/          (システムDB除外)
AllUserDatabases          |
                         v
                   互換性レベルチェック
                   ($db.CompatibilityLevel)
                         |
                         v
Force           ------>  更新要否判定
                         |
                         v
                   $db.CompatibilityLevel更新
                         |
                         v
                   $db.TargetRecoveryTime更新
                   (SQL 2016以降)
                         |
NoCheckDb       ------>  DBCC CHECKDB DATA_PURITY
                         |
                         v
NoUpdateUsage   ------>  DBCC UPDATEUSAGE
                         |
                         v
NoUpdateStats   ------>  sp_updatestats
                         |
                         v
NoRefreshView   ------>  sp_refreshview
                         (各ユーザービュー)
                         |
                         v
                   PSCustomObject  ----->  出力
                   (Compatibility, DataPurity,
                    UpdateUsage, UpdateStats,
                    RefreshViews)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaDbUpgrade.ps1 | `public/Invoke-DbaDbUpgrade.ps1` | ソース | データベースアップグレードコマンド |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | インスタンス接続 |
