# 機能設計書 338-Repair-DbaInstanceName

## 概要

本ドキュメントは、SQL Serverの@@SERVERNAMEシステム変数をWindowsホスト名と一致するように更新する機能「Repair-DbaInstanceName」の設計仕様を記載する。

### 本機能の処理概要

Repair-DbaInstanceNameは、SQL Serverの@@SERVERNAMEシステム変数を現在のWindowsホスト名と一致するように更新する機能である。Windowsサーバーの名前変更後に必要な修正を行い、Kerberos認証や可用性グループの適切な機能を確保する。

**業務上の目的・背景**：Windowsサーバーの名前が変更された場合、SQL Serverの@@SERVERNAME値は自動的に更新されない。この不一致はKerberos認証の失敗、可用性グループの問題、その他のSQL Server機能の不具合を引き起こす可能性がある。本機能は、この問題を検出し、自動的に修正することで、サーバー名変更後の追加作業を簡素化する。

**機能の利用シーン**：
- Windowsサーバーの名前変更後にSQL Serverを更新する際
- サーバー名の不一致によるKerberos認証の問題を解決する際
- 可用性グループ環境でのサーバー名の問題を修正する際
- サーバー移行やクローン作成後の名前修正を行う際

**主要な処理内容**：
1. Test-DbaInstanceName を呼び出して名前変更の必要性を判定
2. ブロッカー（レプリケーション、ミラーリング）の検出と対処
3. sp_dropserver で古いサーバー名を削除
4. sp_addserver で新しいサーバー名を追加
5. SQL Serverサービスの再起動
6. 結果の検証

**関連システム・外部連携**：
- SQL Server システムストアドプロシージャ（sp_dropserver、sp_addserver）
- Windows サービス管理
- SQL Server Reporting Services（警告対象）

**権限による制御**：
- sysadmin ロールまたは ALTER ANY LOGIN 権限が必要
- Windowsサービス制御にはローカル管理者権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

設定変更 / インスタンス管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | - |
| AutoFix | switch | No | ブロッカーを自動的に解決 | - |
| Force | switch | No | 確認プロンプトをバイパス | - |
| EnableException | switch | No | 例外を直接スローする | - |
| WhatIf | switch | No | 実行せずに処理内容を表示 | - |
| Confirm | switch | No | 実行前に確認プロンプトを表示 | - |

### 入力データソース

- SQL Server @@SERVERNAME システム変数
- Windows NetBIOS名

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| ServerName | string | 変更後のサーバー名 |
| NewServerName | string | 期待されるサーバー名 |
| RenameRequired | bool | 名前変更が必要かどうか |
| Updatable | bool | インスタンスを更新可能かどうか |
| Warnings | string | SSRS関連の警告メッセージ |
| Blockers | object[] | 名前変更を妨げる要因 |

### 出力先

パイプライン出力（PSCustomObject - Test-DbaInstanceNameの結果）

## 処理フロー

### 処理シーケンス

```
1. インスタンス接続
   └─ Connect-DbaInstance で接続（MinimumVersion 9 = SQL Server 2005）

2. クラスターチェック
   └─ クラスターの場合は処理をスキップ（Microsoftはクラスター名変更をサポートしない）

3. 名前変更要否の判定
   └─ Test-DbaInstanceName を呼び出して判定

4. ブロッカーの処理（Updatable = false の場合）
   └─ レプリケーション: AutoFix時はsp_dropdistributorを実行
   └─ ミラーリング: AutoFix時はミラーリングをオフに

5. SSRSの処理
   └─ Reporting Servicesが動作中の場合は停止を提案

6. サーバー名の更新
   └─ sp_dropserver で古い名前を削除
   └─ sp_addserver で新しい名前を追加

7. サービス再起動
   └─ SQL Serverサービスを停止・開始

8. 結果検証
   └─ Test-DbaInstanceName を再度呼び出して確認
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{クラスター?}
    C -->|Yes| D[警告を出力して終了]
    C -->|No| E[Test-DbaInstanceName]
    E --> F{RenameRequired?}
    F -->|No| G[メッセージ出力して終了]
    F -->|Yes| H{Updatable?}
    H -->|Yes| L[SSRSチェック]
    H -->|No| I{AutoFix?}
    I -->|No| J[ブロッカー警告して終了]
    I -->|Yes| K[ブロッカー解除処理]
    K --> L
    L --> M{SSRSが稼働中?}
    M -->|Yes| N[SSRS停止を提案]
    M -->|No| O[sp_dropserver実行]
    N --> O
    O --> P[sp_addserver実行]
    P --> Q{サービス再起動?}
    Q -->|Yes| R[SQLサービス再起動]
    Q -->|No| S[再起動が必要な旨を警告]
    R --> T[Test-DbaInstanceNameで検証]
    S --> T
    T --> U[結果出力]
    U --> V[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2005 (バージョン9)以上が必要 | 常に |
| BR-002 | クラスター除外 | クラスターインスタンスはサポートしない | isClustered = true の場合 |
| BR-003 | ブロッカー処理 | レプリケーションやミラーリングは事前に解除が必要 | AutoFix指定時のみ自動解除 |
| BR-004 | サービス再起動 | 名前変更の反映にはSQLサービスの再起動が必要 | 常に |
| BR-005 | SSRS警告 | Reporting Servicesは名前変更後に再構成が必要 | SSRSがインストールされている場合 |

### 計算ロジック

- NewServerName = NetName (デフォルトインスタンス) または "$NetName\$InstanceName" (名前付きインスタンス)

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 古いサーバー名削除 | sys.servers | DELETE（sp_dropserver経由） | 古いサーバー名エントリを削除 |
| 新しいサーバー名追加 | sys.servers | INSERT（sp_addserver経由） | 新しいサーバー名をLOCALとして追加 |
| レプリケーション解除 | distribution関連 | DELETE（sp_dropdistributor経由） | ディストリビューターを削除（AutoFix時） |

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

#### sys.servers

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | server_id, name | 古いサーバー名 | sp_dropserver経由 |
| INSERT | name, is_local | 新しいサーバー名, LOCAL | sp_addserver経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Function で処理継続 |
| ClusterError | クラスターエラー | クラスターインスタンスを対象とした場合 | 警告メッセージを出力 |
| BlockerError | ブロッカーエラー | レプリケーションやミラーリングが有効 | AutoFix または手動解除を要求 |
| SpDropServerError | ストアドプロシージャエラー | sp_dropserver の実行失敗 | Stop-Function で処理終了 |
| SpAddServerError | ストアドプロシージャエラー | sp_addserver の実行失敗 | Stop-Function で処理終了 |
| ServiceError | サービスエラー | SQLサービスの停止/開始失敗 | 警告メッセージを出力 |

### リトライ仕様

リトライは行わない。

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

sp_dropserver と sp_addserver は個別のトランザクションとして実行される。失敗時はロールバックされるが、中間状態が発生する可能性がある。

## パフォーマンス要件

サービス再起動を含むため、数十秒から数分かかる場合がある。

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

- sysadmin権限またはALTER ANY LOGIN権限が必要
- サービス制御にはローカル管理者権限が必要
- AutoFixを使用する場合、レプリケーションやミラーリングが破壊的に解除される
- -Force パラメータは確認プロンプトをバイパスするため、慎重に使用

## 備考

- SQL Server 2005 (バージョン9)以上で動作
- クラスターインスタンスはサポートされない（Microsoftの制限）
- 名前変更後はReporting Servicesの再構成が必要な場合がある
- https://www.mssqltips.com/sqlservertip/2525/steps-to-change-the-server-name-for-a-sql-server-machine/

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | 出力オブジェクト構造（47-62行目の.OUTPUTS） |

**読解のコツ**: 出力はTest-DbaInstanceNameの結果オブジェクトそのもの。ServerName、NewServerName、RenameRequired等のプロパティを含む。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | パラメータ定義（92-99行目） |

**主要処理フロー**:
1. **101-103行目**: begin - Forceによる確認プロンプトの無効化
2. **105-271行目**: process - メイン処理ループ
3. **106-111行目**: インスタンス接続
4. **113-116行目**: クラスターチェック
5. **121-128行目**: Test-DbaInstanceNameで名前変更要否を判定

#### Step 3: ブロッカー処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | ブロッカー処理（129-199行目） |

**主要処理フロー**:
- **133-160行目**: レプリケーションブロッカーの処理
- **161-197行目**: ミラーリングブロッカーの処理

#### Step 4: サーバー名更新処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | sp_dropserver/sp_addserver実行（225-244行目） |

**主要処理フロー**:
- **226-233行目**: sp_dropserver の実行
- **235-243行目**: sp_addserver の実行

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

```
Repair-DbaInstanceName
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Serverへの接続（MinimumVersion 9）
    │
    ├─ Test-DbaInstanceName
    │      └─ 名前変更の必要性判定
    │
    ├─ ブロッカー解除（AutoFix時）
    │      ├─ $server.Query("EXEC sp_dropdistributor")
    │      └─ $database.ChangeMirroringState(Off)
    │
    ├─ Get-Service / Stop-Service / Start-Service
    │      └─ SQLサービスの制御
    │
    ├─ $server.Query("EXEC sp_dropserver")
    │      └─ 古いサーバー名の削除
    │
    ├─ $server.Query("EXEC sp_addserver")
    │      └─ 新しいサーバー名の追加
    │
    └─ Test-DbaInstanceName（検証用）
           └─ 名前変更結果の確認
```

### データフロー図

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

SqlInstance ──▶ Connect-DbaInstance
                    │
                    ▼
               Test-DbaInstanceName
                    │
                    ├─ oldServerName = @@SERVERNAME
                    ├─ newServerName = NetName[\InstanceName]
                    │
                    ▼
              {ブロッカーチェック}
                    │
                    ├─ レプリケーション解除（AutoFix）
                    ├─ ミラーリング解除（AutoFix）
                    │
                    ▼
               sp_dropserver ──▶ sys.servers から古い名前を削除
                    │
                    ▼
               sp_addserver ──▶ sys.servers に新しい名前を追加
                    │
                    ▼
              SQLサービス再起動
                    │
                    ▼
               Test-DbaInstanceName ──▶ 結果検証 ──▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Repair-DbaInstanceName.ps1 | `public/Repair-DbaInstanceName.ps1` | ソース | メイン関数 |
| Test-DbaInstanceName.ps1 | `public/Test-DbaInstanceName.ps1` | ソース | 名前変更要否の判定 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
