# 機能設計書 339-Test-DbaInstanceName

## 概要

本ドキュメントは、SQL Serverインスタンス名とホストOSの整合性を検証し、名前変更の要件とブロッカーを特定する機能「Test-DbaInstanceName」の設計仕様を記載する。

### 本機能の処理概要

Test-DbaInstanceNameは、SQL Serverインスタンス名（@@SERVERNAME）と実際のホスト名・インスタンスの組み合わせが一致しているかを比較し、一致しない場合に名前変更が必要かどうかを判定する機能である。また、安全な名前変更を妨げる条件のスキャンも実行する。

**業務上の目的・背景**：Windowsサーバーの名前が変更された場合、SQL Serverの@@SERVERNAMEは自動的に更新されないため、名前変更が必要になる。この不一致は認証の問題やクラスター機能の不具合を引き起こす可能性がある。本機能は、名前変更の必要性を事前に判定し、変更を妨げる条件（データベースミラーリング、レプリケーション設定、リモートログイン依存関係）を特定することで、Repair-DbaInstanceNameを実行する前の計画立案を支援する。

**機能の利用シーン**：
- サーバー名変更操作の前に名前変更の必要性を確認する際
- 名前変更を妨げる条件を事前に把握する際
- SQL Server Reporting Servicesのインストールを確認する際
- ディザスタリカバリドキュメントと実際の構成を照合する際

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. @@SERVERNAME と NetName[\InstanceName] の比較
3. SSRS（SQL Server Reporting Services）のインストール確認
4. ブロッカーの検出
   - データベースミラーリング
   - レプリケーション（Publishing、Subscribing、Distribution）
   - リモートログイン
5. 結果をカスタムオブジェクトとして出力

**関連システム・外部連携**：
- SQL Server SMO (Server Management Objects)
- SQL Server システムビュー
- SQL Server Reporting Services

**権限による制御**：
- 基本的な情報取得にはSQL Serverへの接続権限が必要
- レプリケーション情報の取得にはmsdbへのアクセス権限が必要

## 関連画面

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

## 機能種別

検証 / インスタンス管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可能 |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | - |
| ExcludeSsrs | switch | No | SSRSチェックをスキップ | - |
| EnableException | switch | No | 例外を直接スローする | - |

### 入力データソース

- SQL Server @@SERVERNAME システム変数
- SQL Server SMO Server.NetName, Server.InstanceName プロパティ
- sys.databases (is_published, is_subscribed, is_distributor)
- sys.remote_logins, sys.sysservers

## 出力仕様

### 出力データ

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

### 出力先

パイプライン出力（PSCustomObject）

## 処理フロー

### 処理シーケンス

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

2. クラスターチェック
   └─ クラスターの場合は警告メッセージを出力

3. サーバー名の取得
   └─ @@SERVERNAME を取得
   └─ NetName[\InstanceName] を計算

4. 名前変更要否の判定
   └─ ServerName != NewServerName の場合 RenameRequired = true

5. SSRSチェック（ExcludeSsrs未指定時）
   └─ Get-DbaService でSSRSサービスを取得
   └─ 稼働中の場合は警告メッセージを設定

6. ブロッカーチェック
   └─ データベースミラーリングのチェック
   └─ レプリケーションのチェック
   └─ リモートログインのチェック

7. 結果出力
   └─ PSCustomObject としてパイプラインに出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance]
    B --> C{接続成功?}
    C -->|No| D[Stop-Function]
    C -->|Yes| E{クラスター?}
    E -->|Yes| F[警告メッセージ出力]
    E -->|No| G[@@SERVERNAME取得]
    F --> G
    G --> H[NewServerName計算]
    H --> I{名前変更必要?}
    I -->|No| J[RenameRequired = false]
    I -->|Yes| K[RenameRequired = true]
    J --> L[SSRSチェック]
    K --> L
    L --> M{SSRSあり?}
    M -->|Yes| N[Warnings設定]
    M -->|No| O[ミラーリングチェック]
    N --> O
    O --> P{ミラーリングあり?}
    P -->|Yes| Q[Blockers追加]
    P -->|No| R[レプリケーションチェック]
    Q --> R
    R --> S{レプリケーションあり?}
    S -->|Yes| T[Blockers追加]
    S -->|No| U[リモートログインチェック]
    T --> U
    U --> V{リモートログインあり?}
    V -->|Yes| W[Blockers追加]
    V -->|No| X[Updatable判定]
    W --> X
    X --> Y[PSCustomObject出力]
    Y --> Z[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 最小バージョン | SQL Server 2005 (バージョン9)以上が必要 | 常に |
| BR-002 | クラスター警告 | クラスターインスタンスは名前変更をサポートしない | isClustered = true の場合 |
| BR-003 | NewServerName計算 | デフォルトインスタンスはNetName、名前付きはNetName\InstanceName | InstanceName.Length による分岐 |
| BR-004 | Updatable判定 | Blockersが存在する場合はfalse、存在しない場合はtrue | Blockers.Length による判定 |

### 計算ロジック

- RenameRequired = (NewServerName != ServerName)
- NewServerName = NetName（デフォルトインスタンス）または "$NetName\$InstanceName"（名前付きインスタンス）
- Updatable = (reasons.Length == 0) ? true : false

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| サーバー名取得 | - | SELECT | @@SERVERNAME システム変数 |
| ミラーリング確認 | sys.databases | SELECT | IsMirroringEnabled プロパティ |
| レプリケーション確認 | sys.databases | SELECT | is_published, is_subscribed, is_distributor |
| リモートログイン確認 | sys.remote_logins, sys.sysservers | SELECT | リモートログイン情報 |

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

本機能は読み取り専用操作のみを行う。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Function で処理継続 |
| SSRSError | SSRSエラー | SSRSサービス情報取得失敗 | 警告ログを出力して処理継続 |

### リトライ仕様

リトライは行わない。

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

本機能はデータ変更を行わないため、トランザクション管理は不要。

## パフォーマンス要件

データベース数に依存するが、通常は即座に完了する。

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

- サーバー構成情報が表示されるため、機密情報として扱う
- レプリケーション情報やリモートログイン情報が含まれる

## 備考

- SQL Server 2005 (バージョン9)以上で動作
- Repair-DbaInstanceName と連携して使用
- https://www.mssqltips.com/sqlservertip/2525/steps-to-change-the-server-name-for-a-sql-server-machine/

---

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

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

### 推奨読解順序

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

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

**読解のコツ**: 出力オブジェクトはPSCustomObjectで、ServerName、NewServerName、RenameRequired、Updatable、Warnings、Blockersの各プロパティを含む。

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

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

**主要処理フロー**:
1. **95-102行目**: インスタンス接続
2. **104-106行目**: クラスターチェック
3. **108-122行目**: ServerNameとNewServerNameの取得
4. **132-142行目**: serverInfoオブジェクトの作成
5. **144-204行目**: ブロッカーチェック

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

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

**主要処理フロー**:
- **169行目**: $server.Databases | Where-Object IsMirroringEnabled
- **179行目**: is_published, is_subscribed, is_distributor のSQLクエリ
- **189行目**: sys.remote_logins と sys.sysservers のJOINクエリ

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

```
Test-DbaInstanceName
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Serverへの接続（MinimumVersion 9）
    │
    ├─ $server.Query("SELECT @@servername")
    │      └─ 現在のサーバー名を取得
    │
    ├─ Get-DbaService -Type SSRS
    │      └─ SSRSサービス情報取得
    │
    ├─ $server.Databases (IsMirroringEnabled)
    │      └─ ミラーリング構成のデータベース取得
    │
    ├─ $server.Query() (is_published等)
    │      └─ レプリケーション構成のデータベース取得
    │
    └─ $server.Query() (sys.remote_logins)
           └─ リモートログイン情報取得
```

### データフロー図

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

SqlInstance ──▶ Connect-DbaInstance
                    │
                    ▼
               @@SERVERNAME取得
                    │
                    ├─ ServerName = @@SERVERNAME
                    ├─ NetName = $server.NetName
                    ├─ InstanceName = $server.InstanceName
                    │
                    ▼
               NewServerName計算
                    │
                    ├─ InstanceName.Length == 0 → NewServerName = NetName
                    ├─ InstanceName.Length > 0  → NewServerName = NetName\InstanceName
                    │
                    ▼
               RenameRequired = (ServerName != NewServerName)
                    │
                    ▼
               ブロッカーチェック
                    │
                    ├─ SSRS → Warnings
                    ├─ Mirroring → Blockers
                    ├─ Replication → Blockers
                    ├─ RemoteLogins → Blockers
                    │
                    ▼
               Updatable判定
                    │
                    ▼
               PSCustomObject ──▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| 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サービス情報取得 |
