# 機能設計書 231-Set-DbaTempDbConfig

## 概要

本ドキュメントは、dbatools PowerShellモジュールのSet-DbaTempDbConfig関数に関する機能設計書です。この関数はSQL Serverのtempdbデータベースファイルをマイクロソフトのベストプラクティスに従って構成します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのtempdbは全てのデータベース操作で使用される共有リソースであり、パフォーマンスに直接影響します。論理CPUコア数に応じた適切なデータファイル数の設定、ファイルサイズの均等配分、適切な成長設定は、パフォーマンス最適化の重要な要素です。本機能は、これらの設定を自動計算し、マイクロソフト推奨のベストプラクティスに従ったtempdb構成を実現します。

**機能の利用シーン**：新規SQL Serverインスタンスのセットアップ時、パフォーマンスチューニング時、tempdbのサイズ変更が必要な場合、複数インスタンスの一括構成時などに使用されます。

**主要な処理内容**：
1. SQL Serverインスタンスへの接続とバージョン確認（SQL Server 2005以上が必要）
2. 論理CPUコア数に基づくデータファイル数の自動計算（最大8ファイル）
3. 指定された合計サイズのファイル間均等配分計算
4. 既存tempdb構成の検証（現在のファイルサイズ・ファイル数との整合性確認）
5. ALTER DATABASE文の生成と実行
6. 構成変更後の結果オブジェクト出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)を使用してSQL Serverインスタンスと連携します。

**権限による制御**：tempdbの変更にはALTER DATABASE権限が必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | CLIコマンド | 主機能 | PowerShellコマンドラインから直接実行 |

## 機能種別

構成変更処理（Database Configuration）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | SQL Server 2005以上 |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | - |
| DataFileCount | int | No | データファイル数（省略時はCPUコア数、最大8） | コア数超過時は警告 |
| DataFileSize | int | Yes | 全データファイルの合計サイズ（MB） | 必須 |
| LogFileSize | int | No | ログファイルサイズ（MB） | - |
| DataFileGrowth | int | No | データファイル成長サイズ（MB、デフォルト512） | - |
| LogFileGrowth | int | No | ログファイル成長サイズ（MB、デフォルト512） | - |
| DataPath | string[] | No | データファイル格納パス | パスの存在確認 |
| LogPath | string | No | ログファイル格納パス | パスの存在確認 |
| OutFile | string | No | SQLスクリプト出力先ファイルパス | - |
| OutputScriptOnly | switch | No | SQL文生成のみ（実行しない） | - |
| DisableGrowth | switch | No | ファイル成長を無効化 | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドライン引数
- SQL Serverインスタンスからの現在のtempdb構成情報（sys.database_files）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なインスタンス名 |
| DataFileCount | int | 設定されたデータファイル数 |
| DataFileSize | dbasize | 全データファイル合計サイズ |
| SingleDataFileSize | dbasize | 個別データファイルサイズ |
| LogSize | dbasize | ログファイルサイズ |
| DataPath | string/string[] | データファイルパス |
| LogPath | string | ログファイルパス |
| DataFileGrowth | dbasize | データファイル成長サイズ |
| LogFileGrowth | dbasize | ログファイル成長サイズ |

### 出力先

- デフォルト：PSCustomObjectをパイプラインに出力
- OutputScriptOnly指定時：ALTER DATABASE文の配列を返却
- OutFile指定時：指定ファイルにSQL文を書き出し

## 処理フロー

### 処理シーケンス

```
1. SQL Serverインスタンスへ接続
   └─ MinimumVersion 9（SQL Server 2005）を指定
2. CPUコア数の取得と上限設定
   └─ 8を超える場合は8に制限
3. DataFileCountの決定
   └─ 未指定時はコア数、指定時はベストプラクティス警告
4. 個別ファイルサイズの計算
   └─ DataFileSize / DataFileCount（切り捨て）
5. データパス・ログパスの検証
   └─ 未指定時は現在のtempdbパスを使用
6. 成長設定の処理
   └─ DisableGrowth時は0に設定
7. 現在のtempdb構成検証
   └─ ファイル数・サイズの整合性確認
8. ALTER DATABASE文の生成
   └─ 既存ファイルはMODIFY、新規はADD
9. SQL実行または出力
   └─ モードに応じて実行/スクリプト出力/ファイル出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQL Server接続]
    B --> C{接続成功?}
    C -->|No| Z[エラー終了]
    C -->|Yes| D[CPUコア数取得]
    D --> E{コア > 8?}
    E -->|Yes| F[コア = 8]
    E -->|No| G[コア維持]
    F --> H[DataFileCount決定]
    G --> H
    H --> I[ファイルサイズ計算]
    I --> J[パス検証]
    J --> K{パス有効?}
    K -->|No| Z
    K -->|Yes| L[現在のtempdb検証]
    L --> M{検証OK?}
    M -->|No| Z
    M -->|Yes| N[ALTER DATABASE文生成]
    N --> O{OutputScriptOnly?}
    O -->|Yes| P[SQL文返却]
    O -->|No| Q{OutFile?}
    Q -->|Yes| R[ファイル出力]
    Q -->|No| S[SQL実行]
    S --> T[結果出力]
    P --> U[終了]
    R --> U
    T --> U
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | データファイル数上限 | CPUコア数は最大8に制限 | 常時 |
| BR-002 | ベストプラクティス警告 | DataFileCountがコア数を超過時に警告 | DataFileCount明示指定時 |
| BR-003 | ファイルサイズ整合性 | 現在のファイルサイズより小さい設定は不可 | 常時 |
| BR-004 | ファイル数整合性 | 現在のファイル数より少ない設定は不可 | 常時 |
| BR-005 | 成長無効化優先 | DisableGrowth指定時は成長パラメータを0に上書き | DisableGrowth指定時 |

### 計算ロジック

- 個別データファイルサイズ = Math.Floor(DataFileSize / DataFileCount)
- ファイル配置：複数DataPath指定時はラウンドロビン方式で分散

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| tempdb構成変更 | tempdb | ALTER DATABASE | データファイル・ログファイルの変更/追加 |
| 構成情報取得 | sys.database_files | SELECT | 現在のファイル構成取得 |

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

#### sys.database_files（参照）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | physical_name | file_id = 1 または 2 | パス取得 |
| SELECT | size | type = 0 | 現在のデータファイルサイズ確認 |
| SELECT | COUNT(*) | type = 0 | 現在のデータファイル数確認 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Server接続失敗 | インスタンス名・認証情報確認 |
| InvalidPath | パスエラー | DataPath/LogPathが存在しない | 正しいパスを指定 |
| ConfigConflict | 構成競合 | 現在のファイル数が目標より多い | 手動でファイル削除後に再実行 |
| SizeConflict | サイズ競合 | 現在のファイルサイズが目標より大きい | 手動で縮小後に再実行 |

### リトライ仕様

リトライ処理は実装されていません。エラー発生時は処理を停止し、次のインスタンスに進みます。

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

ALTER DATABASE文はSQL Server内部でトランザクション管理されます。複数のALTER文は一括実行されますが、個別にコミットされます。

## パフォーマンス要件

- tempdb構成変更は即座に適用されるが、変更を有効にするにはSQL Serverの再起動が必要
- 複数インスタンス処理時は順次処理

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

- ALTER DATABASE権限が必要
- SqlCredential使用時はSecureStringで資格情報を保護
- ファイルパスはSQL Serverサービスアカウントがアクセス可能である必要あり

## 備考

- 設定変更後はSQL Serverサービスの再起動が必要
- 既存ファイルの縮小・削除は行わない
- SQL Server 2005以上が必要（MinimumVersion 9指定）

---

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

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

### 推奨読解順序

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

本機能で使用される主要なデータ構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaTempDbConfig.ps1 | `public/Set-DbaTempDbConfig.ps1` | 出力オブジェクトの構造（296-308行目のPSCustomObject） |

**読解のコツ**: dbatools特有の[dbasize]型は、バイト、KB、MB、GBなど様々な単位に変換可能なサイズオブジェクトです。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaTempDbConfig.ps1 | `public/Set-DbaTempDbConfig.ps1` | 関数定義とパラメータブロック（136-154行目） |

**主要処理フロー**:
1. **156-161行目**: SQL Serverへの接続（Connect-DbaInstance使用、MinimumVersion 9）
2. **163-166行目**: CPUコア数取得と上限8への制限
3. **169-177行目**: DataFileCountの決定とベストプラクティス警告
4. **179-180行目**: 個別ファイルサイズの計算
5. **182-208行目**: データパス・ログパスの検証
6. **211-214行目**: DisableGrowth処理
7. **217-226行目**: 現在のtempdb構成との整合性検証
8. **236-262行目**: ALTER DATABASE文の生成ループ
9. **286-315行目**: 出力モードに応じた処理分岐

#### Step 3: SQL生成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaTempDbConfig.ps1 | `public/Set-DbaTempDbConfig.ps1` | ALTER DATABASE文生成（236-281行目） |

**主要処理フロー**:
- **236-262行目**: データファイルのMODIFY/ADD文生成
- **252-256行目**: 既存ファイルの変更文生成
- **258-260行目**: 新規ファイルの追加文生成
- **264-281行目**: ログファイルの変更文生成

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

```
Set-DbaTempDbConfig
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ Test-Bound
    │      └─ パラメータバインド確認
    │
    ├─ Test-DbaPath
    │      └─ SQL Serverからのパスアクセス確認
    │
    ├─ Get-DbaDbFile
    │      └─ tempdbファイル情報取得
    │
    └─ ExecuteNonQuery
           └─ ALTER DATABASE実行
```

### データフロー図

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

SqlInstance ──────────┐
                      │
DataFileSize ─────────┤
                      ├──▶ Set-DbaTempDbConfig ─────────────────┬──▶ PSCustomObject
DataPath ─────────────┤         │                                │
                      │         ├─ Connect-DbaInstance           ├──▶ SQL Script
LogPath ──────────────┤         ├─ Calculate file sizes          │
                      │         ├─ Validate current config       └──▶ File Output
OutputScriptOnly ─────┤         ├─ Generate ALTER DATABASE
                      │         └─ Execute or Output
OutFile ──────────────┘

[sys.database_files] ◄──────── Query ──────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaTempDbConfig.ps1 | `public/Set-DbaTempDbConfig.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続ヘルパー |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス検証ヘルパー |
| Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | ソース | データベースファイル情報取得 |
| Test-Bound.ps1 | `private/functions/Test-Bound.ps1` | ソース | パラメータバインド確認 |
| Set-DbaTempDbConfig.Tests.ps1 | `tests/Set-DbaTempDbConfig.Tests.ps1` | テスト | 単体テスト |
