# 画面設計書 99-インスタンス名テスト

## 概要

本ドキュメントはdbatools PowerShellモジュールにおけるインスタンス名テスト・修復機能（Test-DbaInstanceName、Repair-DbaInstanceName）の画面設計書です。

### 本画面の処理概要

**業務上の目的・背景**：
Windows Serverのホスト名が変更された場合、SQL Serverの@@SERVERNAME変数も更新する必要があります。この不整合は、可用性グループやKerberos認証で問題を引き起こす可能性があります。本機能群は、SQL Serverインスタンス名とホストOSの整合性を検証し、不整合がある場合は安全にリネームを実行できるかどうかを判定します。データベースミラーリング、レプリケーション、リモートログインなどのリネームを阻害する要因も検出し、必要に応じて自動修復を行います。

**画面へのアクセス方法**：
PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスします。
- `Test-DbaInstanceName -SqlInstance <インスタンス名>`
- `Repair-DbaInstanceName -SqlInstance <インスタンス名>`

**主要な操作・処理内容**：
1. **名前整合性チェック**：@@SERVERNAMEとホスト名+インスタンス名の比較
2. **ブロッカー検出**：データベースミラーリング、レプリケーション、リモートログインの検出
3. **SSRS警告**：SQL Server Reporting Servicesがインストールされている場合の警告
4. **名前修復**：sp_dropserverとsp_addserverによるサーバー名の更新
5. **サービス再起動**：リネーム完了後のSQL Serverサービス再起動

**画面遷移**：
Test-DbaInstanceNameで問題を検出した後、Repair-DbaInstanceNameで修復を実行する。修復後は自動的にTest-DbaInstanceNameを再実行して結果を確認する。

**権限による表示制御**：
- SQL Serverインスタンスへの接続権限が必要
- サーバー名変更にはsysadmin権限が必要
- サービス再起動にはWindows管理者権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 339 | Test-DbaInstanceName | 主機能 | インスタンス名のテスト |
| 338 | Repair-DbaInstanceName | 補助機能 | インスタンス名の修復 |

## 画面種別

CLI（コマンドラインインターフェース）/ 検証・修復

## URL/ルーティング

PowerShellコマンド:
- `Test-DbaInstanceName`
- `Repair-DbaInstanceName`

## 入出力項目

### Test-DbaInstanceName パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance[] | はい | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の資格情報 |
| ExcludeSsrs | switch | いいえ | SSRSチェックをスキップ |
| EnableException | switch | いいえ | 例外を有効化 |

### Repair-DbaInstanceName パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | 対象のSQL Serverインスタンス |
| SqlCredential | PSCredential | いいえ | SQL Server接続用の資格情報 |
| AutoFix | switch | いいえ | ブロッカーを自動的に解決（レプリケーション、ミラーリングを破棄） |
| Force | switch | いいえ | 確認プロンプトをバイパス |
| WhatIf | switch | いいえ | 実行内容のプレビュー |
| Confirm | switch | いいえ | 確認プロンプト |
| EnableException | switch | いいえ | 例外を有効化 |

## 表示項目

### Test-DbaInstanceName / Repair-DbaInstanceName 出力

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| ServerName | string | @@SERVERNAMEから取得した現在のサーバー名 |
| NewServerName | string | ホスト名とインスタンス名に基づく期待されるサーバー名 |
| RenameRequired | bool | リネームが必要かどうか |
| Updatable | bool/string | 安全にリネーム可能か（true/false/"N/A"） |
| Warnings | string | SSRS関連の警告メッセージ（"N/A"の場合なし） |
| Blockers | string[] | リネームを阻害する理由の配列（"N/A"の場合なし） |

### ブロッカーの種類

| ブロッカータイプ | 説明 | 検出方法 |
|------------------|------|----------|
| データベースミラーリング | ミラーリングが有効なデータベースが存在 | IsMirroringEnabled = true |
| レプリケーション | is_published/is_subscribed/is_distributor = 1 | sys.databases |
| リモートログイン | sys.remote_loginsにエントリが存在 | sys.remote_logins JOIN sys.sysservers |

## イベント仕様

### 1-名前整合性テスト（Test-DbaInstanceName）

1. Connect-DbaInstanceでSQL Server接続（MinimumVersion 9）
2. クラスター環境の場合は警告メッセージ出力
3. @@SERVERNAMEで現在のサーバー名を取得
4. $server.NetNameと$server.InstanceNameから期待される名前を構築
5. SSRSサービスの存在を確認
6. データベースミラーリングをチェック
7. レプリケーションをチェック
8. リモートログインをチェック
9. 結果オブジェクトを出力

### 2-名前修復処理（Repair-DbaInstanceName）

1. Connect-DbaInstanceでSQL Server接続（MinimumVersion 9）
2. クラスター環境の場合はスキップ
3. Test-DbaInstanceNameで現在の状態を確認
4. リネームが不要な場合はスキップ
5. ブロッカーが存在する場合：
   - AutoFixなしの場合はエラー終了
   - AutoFixありの場合は確認後、sp_dropdistributorやミラーリング解除を実行
6. SSRSサービスが実行中の場合は停止確認
7. sp_dropserverで古いサーバー名を削除
8. sp_addserverで新しいサーバー名を追加
9. SQL Serverサービスを再起動
10. Test-DbaInstanceNameで結果を確認

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| 名前テスト | @@SERVERNAME | SELECT | 現在のサーバー名取得 |
| ミラーリングチェック | sys.databases | SELECT | IsMirroringEnabled確認 |
| レプリケーションチェック | sys.databases | SELECT | is_published/is_subscribed/is_distributor確認 |
| リモートログインチェック | sys.remote_logins | SELECT | リモートログイン存在確認 |
| 名前削除 | sys.servers | DELETE | sp_dropserverによる削除 |
| 名前追加 | sys.servers | INSERT | sp_addserverによる追加 |
| レプリケーション削除 | distribution | DELETE | sp_dropdistributorによる削除 |
| ミラーリング解除 | sys.database_mirroring | UPDATE | ChangeMirroringState(Off) |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 |
|-------------|------|---------------|
| MSG001 | 警告 | {instance} is a cluster. Renaming clusters is not supported by Microsoft. |
| MSG002 | 情報 | configuredServerName from @@servername is {configuredServerName} |
| MSG003 | 警告 | Unable to pull information on {ssrsService}. |
| MSG004 | 情報 | Good news! {oldServerName}'s @@SERVERNAME does not need to be changed. |
| MSG005 | 情報 | Test-DbaInstanceName reports that the rename cannot proceed |
| MSG006 | エラー | Cannot proceed because some databases are involved in replication. |
| MSG007 | エラー | Cannot proceed because some databases are being mirrored. |
| MSG008 | 情報 | Performing sp_dropdistributor @no_checks = 1. |
| MSG009 | 警告 | You must reconfigure Reporting Services once the server has been successfully renamed. |
| MSG010 | 情報 | Performing sp_dropserver to remove the old server name, then sp_addserver to add {newServerName} |
| MSG011 | 情報 | {instance} successfully renamed from {oldServerName} to {newServerName}. |
| MSG012 | 警告 | SQL Service restart for {newServerName} still required. |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラー出力し、処理を継続 |
| クラスター環境 | 警告メッセージを出力し、Repairはスキップ |
| ブロッカー存在（AutoFixなし） | Stop-Functionでエラー出力、処理終了 |
| sp_dropserver失敗 | Stop-Functionでエラー出力、処理終了 |
| sp_addserver失敗 | Stop-Functionでエラー出力、処理終了 |
| サービス再起動失敗 | Stop-Functionでエラー出力し、処理を継続 |

## 備考

- SQL Server 2005以降が必要（MinimumVersion 9）
- クラスター環境でのリネームはMicrosoftがサポートしていない
- サーバー名変更後はSQL Serverサービスの再起動が必要
- SSRSがインストールされている場合は、リネーム後にSSRS構成マネージャーで再設定が必要
- -AutoFixと-Forceを組み合わせることで完全自動化が可能

---

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

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

### 推奨読解順序

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

出力されるPSCustomObjectの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | 48-63行目の.OUTPUTSセクション |

**読解のコツ**: RenameRequired, Updatable, Blockers の関係性を理解する。

#### Step 2: 名前整合性チェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | 88-94行目のparamブロック |
| 2-2 | Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | 108-122行目の名前計算ロジック |

**主要処理フロー**:
- **99行目**: MinimumVersion 9でSQL Server接続
- **104-106行目**: クラスター環境の警告
- **108行目**: @@SERVERNAMEで現在の名前取得
- **116-121行目**: 期待される名前の計算

#### Step 3: ブロッカーチェックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | 168-176行目（ミラーリングチェック） |
| 3-2 | Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | 178-186行目（レプリケーションチェック） |
| 3-3 | Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | 188-196行目（リモートログインチェック） |

**主要処理フロー**:
- **169行目**: $server.Databases | Where IsMirroringEnabled
- **179-181行目**: sys.databasesからレプリケーション状態をクエリ
- **189-191行目**: sys.remote_loginsからリモートログインをクエリ

#### Step 4: 名前修復ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | 92-99行目のparamブロック |
| 4-2 | Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | 121-127行目のTest-DbaInstanceName呼び出し |
| 4-3 | Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | 225-244行目のsp_dropserver/sp_addserver |

**主要処理フロー**:
- **121行目**: Test-DbaInstanceNameで状態確認
- **129-199行目**: ブロッカー処理（AutoFix含む）
- **226行目**: sp_dropserver実行
- **235行目**: sp_addserver実行
- **251-260行目**: サービス再起動

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

```
Test-DbaInstanceName
    │
    ├─ Connect-DbaInstance (MinimumVersion 9)
    │      └─ SQL Server接続確立
    │
    ├─ $server.Query("SELECT @@servername")
    │      └─ 現在のサーバー名取得
    │
    ├─ Get-DbaService (SSRS)
    │      └─ SSRSサービス確認
    │
    ├─ $server.Databases (IsMirroringEnabled)
    │      └─ ミラーリングチェック
    │
    ├─ $server.Query("sys.databases")
    │      └─ レプリケーションチェック
    │
    └─ $server.Query("sys.remote_logins")
           └─ リモートログインチェック

Repair-DbaInstanceName
    │
    ├─ Connect-DbaInstance (MinimumVersion 9)
    │      └─ SQL Server接続確立
    │
    ├─ Test-DbaInstanceName
    │      └─ 現在の状態確認
    │
    ├─ sp_dropdistributor (AutoFix時)
    │      └─ レプリケーション削除
    │
    ├─ ChangeMirroringState(Off) (AutoFix時)
    │      └─ ミラーリング解除
    │
    ├─ Stop-Service (SSRS)
    │      └─ SSRSサービス停止
    │
    ├─ sp_dropserver
    │      └─ 古いサーバー名削除
    │
    ├─ sp_addserver
    │      └─ 新しいサーバー名追加
    │
    ├─ Stop-Service / Start-Service
    │      └─ SQL Serverサービス再起動
    │
    └─ Test-DbaInstanceName
           └─ 結果確認
```

### データフロー図

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

SqlInstance ─────────────▶ Connect-DbaInstance
                                  │
                          ┌───────▼───────┐
                          │ @@SERVERNAME  │
                          │ 取得          │
                          └───────────────┘
                                  │
                          ┌───────▼───────┐
                          │ 期待される名前│
                          │ 計算          │
                          │ (NetName\     │
                          │  InstanceName)│
                          └───────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        ▼                         ▼                         ▼
   SSRSチェック            ミラーリング             レプリケーション
   (Get-DbaService)         チェック                  チェック
        │                         │                         │
        ▼                         ▼                         ▼
    Warnings               Blockers[]               Blockers[]
        │                         │                         │
        └─────────────────────────┼─────────────────────────┘
                                  ▼
                          ┌───────────────┐
                          │ Updatable     │
                          │ 判定          │
                          └───────────────┘
                                  │
                                  ▼
                          [PSCustomObject]
                          (ServerName,
                           NewServerName,
                           RenameRequired,
                           Updatable,
                           Warnings,
                           Blockers)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | ソース | インスタンス名テスト |
| Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | ソース | インスタンス名修復 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
| Get-DbaService.ps1 | `public/Get-DbaService.ps1` | ソース | SQL Serverサービス取得 |
