# 画面設計書 179-データファイルバランス

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Invoke-DbaBalanceDataFiles` コマンドの機能仕様を定義した画面設計書です。

### 本画面の処理概要

本コマンドは、複数のデータファイル間でデータを再バランスし、均等なデータ分散を実現します。

**業務上の目的・背景**：大規模なデータベースに新しいデータファイルを追加した場合、SQL Serverは新しいファイルが既存ファイルとほぼ同じサイズになるまで新しいファイルのみを使用します。これにより、一時的にI/Oの不均衡が生じます。本コマンドを使用することで、DBAはクラスタードインデックスを再構築してデータを複数のデータファイル間で均等に分散させることができます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Invoke-DbaBalanceDataFiles` コマンドを実行します。SqlInstanceとDatabaseを必須パラメータとして指定します。

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスに接続
2. サーバーのエディションとバージョンを確認してオンライン再構築のサポートを判定
3. Windowsの場合、ディスク空き容量を確認
4. 2つ以上のデータファイルを持つファイルグループを特定
5. 対象テーブルのクラスタードインデックスを再構築
6. 再構築前後のデータファイル情報を返却

**画面遷移**：本コマンドは単独実行可能です。出力結果は他のPowerShellコマンドにパイプで渡すことができます。

**権限による表示制御**：ALTER INDEX権限が必要です。オンライン再構築にはEnterprise/Developerエディションが必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 643 | Invoke-DbaBalanceDataFiles | 主機能 | データファイルのバランス調整 |

## 画面種別

コマンドライン出力（処理結果表示）

## URL/ルーティング

PowerShellコマンド: `Invoke-DbaBalanceDataFiles`

## 入出力項目

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証用資格情報 |
| Database | object[] | No | 対象データベース（必須だがエラーで案内） |
| Table | object[] | No | 対象テーブル |
| RebuildOffline | switch | No | オフライン再構築を強制 |
| EnableException | switch | No | 例外処理モードの有効化 |
| Force | switch | No | ディスク容量チェックをバイパス |
| WhatIf | switch | No | 実行せずに変更内容を表示 |
| Confirm | switch | No | 実行前に確認を要求 |

## 表示項目

| 項目名 | 型 | 説明 |
|--------|---|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | 処理対象データベース名 |
| Start | datetime | バランス処理開始日時 |
| End | datetime | バランス処理終了日時 |
| Elapsed | string | 経過時間（HH:mm:ss形式） |
| Success | bool | 処理成功フラグ |
| Unsuccessful | string | バランスできなかったテーブル名（カンマ区切り） |
| DataFilesStart | array | 処理前のデータファイル情報（ID, LogicalName, PhysicalName, Size, UsedSpace, AvailableSpace） |
| DataFilesEnd | array | 処理後のデータファイル情報 |

## イベント仕様

### 1-コマンド実行

1. SqlInstanceに接続
2. Databaseパラメータを検証（未指定の場合エラー）
3. サーバーバージョン/エディションを確認してオンライン再構築サポートを判定
4. RebuildOfflineでない場合、Enterprise/Developer以外はユーザーに確認
5. 処理前のデータファイル情報を取得
6. Windowsの場合、ディスク空き容量を確認（Forceでスキップ可能）
7. データベースが2つ以上のデータファイルを持つか確認
8. 2つ以上のファイルを持つ書き込み可能ファイルグループを特定
9. 対象テーブルのクラスタードインデックスを再構築
10. 処理後のデータファイル情報を取得
11. 結果をPSCustomObjectとして出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| インデックス再構築 | クラスタードインデックス | ALTER | インデックスの再構築によるデータ再配置 |

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

#### クラスタードインデックス

| 操作 | 項目 | 更新内容 | 備考 |
|-----|-----|---------|------|
| REBUILD | インデックス | データの物理的再配置 | オンライン/オフラインモード選択可能 |

## メッセージ仕様

| メッセージID | 種別 | 条件 | メッセージ内容 |
|-------------|------|------|--------------|
| M001 | Error | 接続失敗 | "Failure" |
| M002 | Error | Database未指定 | "Please supply a database to balance out" |
| M003 | Warning | ディスク容量不足 | "The available space may not be sufficient to continue the process. Please use -Force to try anyway." |
| M004 | Error | データファイル1つのみ | "Database {db} only has one data file. Please add a data file to balance out the data" |
| M005 | Error | テーブルにインデックスなし | "Table {tbl} does not contain any indexes" |
| M006 | Error | クラスタードインデックスなし | "No clustered indexes found in table {tbl}" |
| M007 | Verbose | バランス不可 | "Table {tbl} cannot be balanced out" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続失敗 | Stop-Functionでエラーを出力し、次のインスタンスに継続 |
| Database未指定 | Stop-Functionでエラーを出力して終了 |
| データベースが存在しない | Stop-Functionでエラーを出力し、次のインスタンスに継続 |
| インデックス再構築失敗 | エラーを記録し、Unsuccessfulリストに追加して継続 |

## 備考

- ヒープテーブル（クラスタードインデックスのないテーブル）はサポートされません
- オンライン再構築はEnterprise/Developerエディション、SQL Server 2005以降で利用可能
- 非Windows環境ではディスク容量チェックが行われないため、Forceパラメータの使用を推奨
- 処理中はテーブルへのアクセスが制限される可能性があります（特にオフライン再構築時）

---

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

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

### 推奨読解順序

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

出力オブジェクトのプロパティ構成を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Invoke-DbaBalanceDataFiles.ps1 | `public/Invoke-DbaBalanceDataFiles.ps1` | 375-387行目：出力オブジェクトのプロパティ定義 |

**読解のコツ**: DataFilesStart/DataFilesEndは配列で、各要素はGet-DbaDbFileから取得したファイル情報です。

#### Step 2: エディション判定を理解する

オンライン再構築サポートの判定ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Invoke-DbaBalanceDataFiles.ps1 | `public/Invoke-DbaBalanceDataFiles.ps1` | 157-183行目：エディション判定 |

**主要処理フロー**:
- **157-158行目**: RebuildOfflineの場合はオフラインで続行
- **159行目**: SQL Server 2005未満またはEnterprise/Developer以外の場合
- **161-180行目**: ユーザーに確認ダイアログを表示
- **181-182行目**: SQL Server 2005以降かつEnterprise/Developerの場合はオンライン対応

#### Step 3: ファイルグループ判定を理解する

バランス可能なファイルグループの特定ロジックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Invoke-DbaBalanceDataFiles.ps1 | `public/Invoke-DbaBalanceDataFiles.ps1` | 269-275行目：ファイルグループ判定 |

**主要処理フロー**:
- **269行目**: データベースのファイルグループを取得
- **272行目**: ファイル数が2以上かつReadonlyでないファイルグループ
- **273行目**: そのファイルグループ内のオブジェクトを列挙

#### Step 4: インデックス再構築を理解する

クラスタードインデックス再構築の処理フローを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Invoke-DbaBalanceDataFiles.ps1 | `public/Invoke-DbaBalanceDataFiles.ps1` | 306-345行目：インデックス再構築 |

**主要処理フロー**:
- **296行目**: クラスタードインデックスを取得
- **314行目**: オリジナルのOnlineIndexOperation設定を保存
- **317-322行目**: 再構築モードを設定
- **327行目**: $ci.Rebuild()でインデックスを再構築
- **342-343行目**: オリジナル設定を復元

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

```
Invoke-DbaBalanceDataFiles
    |
    +-- Connect-DbaInstance
    |
    +-- エディション判定
    |      (Enterprise/Developer -> オンライン可)
    |
    +-- Get-DbaDbFile (処理前)
    |
    +-- ディスク容量確認 (Windows のみ)
    |
    +-- ファイルグループ判定
    |      (2ファイル以上、Readonly=false)
    |
    +-- foreach ($tbl in $tableCollection)
    |      |
    |      +-- クラスタードインデックス取得
    |      |
    |      +-- $ci.Rebuild() (インデックス再構築)
    |
    +-- Get-DbaDbFile (処理後)
    |
    +-- PSCustomObject (結果出力)
```

### データフロー図

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

SqlInstance,    ---> Connect-DbaInstance
Database              |
                      v
              エディション/バージョン判定
                      |
                      v
              Get-DbaDbFile (Before)    ---> DataFilesStart
                      |
                      v
              ファイルグループ判定
              (2ファイル以上)
                      |
                      v
              foreach テーブル
                      |
                      v
              クラスタードインデックス
              .Rebuild()
                      |
                      v
              Get-DbaDbFile (After)     ---> DataFilesEnd
                      |
                      v
              PSCustomObject           ---> 結果出力
              (Success, Elapsed等)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Invoke-DbaBalanceDataFiles.ps1 | `public/Invoke-DbaBalanceDataFiles.ps1` | ソース | メイン関数実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | ソース | データファイル情報取得 |
