# 画面設計書 255-ログファイル拡張

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Expand-DbaDbLogFile` コマンドに関する画面設計書です。このコマンドは、仮想ログファイル（VLF）の断片化を最小化しながら、トランザクションログファイルをインテリジェントに拡張します。

### 本画面の処理概要

**業務上の目的・背景**：過剰なVLF（仮想ログファイル）は、トランザクションログバックアップの遅延、データベース起動時のリカバリ遅延、極端な場合にはINSERT/UPDATE/DELETE操作のパフォーマンス低下を引き起こします。このコマンドは、SQL Serverバージョンと目標サイズに基づいて最適なインクリメントサイズを計算し、自動増加による過剰なVLF作成を防ぎながら、制御されたチャンクでログを拡張します。プロアクティブなログファイルサイジングや既存のVLF断片化問題の修復に使用します。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Expand-DbaDbLogFile` コマンドを実行します。

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. 対象データベースのログファイル情報を取得
3. ディスク空き容量の検証（オプション）
4. SQL Serverバージョンに応じた最適なインクリメントサイズを計算
5. オプションでログファイルを縮小（トランザクションログバックアップ実行後）
6. チャンク単位でログファイルを拡張
7. 初期/最終のVLF数をレポート

**画面遷移**：CLIコマンドのため画面遷移はありません。

**権限による表示制御**：ALTER DATABASE権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 628 | Expand-DbaDbLogFile | 主機能 | ログファイルの最適な拡張 |
| 637 | Measure-DbaDbVirtualLogFile | 補助機能 | VLF数の測定 |
| 27 | Backup-DbaDatabase | 補助機能 | 縮小前のトランザクションログバックアップ |

## 画面種別

操作実行（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| SqlInstance | DbaInstanceParameter | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | object[] | No | 対象データベース名 |
| ExcludeDatabase | object[] | No | 除外するデータベース名 |
| TargetLogSize | int | Yes | 目標ログサイズ（MB） |
| IncrementSize | int | No | インクリメントサイズ（MB、省略時は自動計算） |
| LogFileId | int | No | 特定のログファイルID |
| ShrinkLogFile | switch | No | 拡張前にログファイルを縮小 |
| ShrinkSize | int | Shrink時必須 | 縮小後のサイズ（MB） |
| BackupDirectory | string | No | ログバックアップの出力先 |
| ExcludeDiskSpaceValidation | switch | No | ディスク空き容量検証をスキップ |
| EnableException | switch | No | 例外を直接スローするかどうか |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | SQL Serverインスタンスのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| DatabaseID | int | データベースID |
| ID | int | ログファイルID |
| Name | string | ログファイルの論理名 |
| InitialSize | dbasize | 操作開始時のログファイルサイズ |
| CurrentSize | dbasize | 操作完了後のログファイルサイズ |
| InitialVLFCount | int | 操作前のVLF数 |
| CurrentVLFCount | int | 操作後のVLF数 |

## 表示項目

CLIコマンドのため、表示項目は出力オブジェクトのプロパティに依存します（Select-DefaultViewでLogFileCountは除外）。

## イベント仕様

### 1-コマンド実行

コマンド実行時に以下の処理が行われます：

1. `Connect-DbaInstance` でSQL Serverに接続
2. バックアップディレクトリの検証（縮小オプション使用時）
3. データベースフィルタリングとログファイル特定
4. 現在のログファイルサイズとVLF数を取得
5. ディスク空き容量の検証（ExcludeDiskSpaceValidationが無効時）
6. SQL Serverバージョンに応じたインクリメントサイズ計算
7. ログファイル縮小処理（オプション）：
   - リカバリモデル確認（Simple以外）
   - トランザクションログバックアップ実行
   - TruncateOnlyで縮小
8. チャンク単位でログファイル拡張
9. 最終VLF数を取得して結果出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| ログファイル拡張 | sys.database_files | ALTER | ログファイルサイズの変更 |
| ログファイル縮小 | sys.database_files | SHRINKFILE | ログファイルの縮小 |
| トランザクションログバックアップ | バックアップ | BACKUP LOG | ログバックアップの実行 |

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

#### sys.database_files

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| ALTER | size | TargetLogSizeに到達するまで増加 | SMOのlogfile.Alter()を使用 |

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| エラー | 接続失敗時 | "Failure" |
| エラー | バックアップディレクトリ不存在 | "Backup directory does not exist." |
| 警告 | Simpleリカバリモデル時 | "Database '$dbName' is in Simple RecoveryModel which does not allow log backups." |
| 警告 | ログバックアップ未実行 | "First, you need to make a full backup before you can do Tlog backup on database '$dbName'" |
| 警告 | インクリメントサイズが推奨値未満 | "The input value for increment size is...less than the suggested value" |
| 情報 | 既にターゲットサイズ以上 | "[INFO] The T-Log file '$logfile' size is already equal or greater than target size" |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理を中断 |
| バックアップディレクトリ不存在 | Stop-Functionで処理を中断 |
| ディスク空き容量不足 | 処理を中断してreturn |
| Simpleリカバリモデル | 警告メッセージを表示してContinue |
| バックアップ失敗 | Stop-Functionで該当DBをスキップ |
| SQL 2012未満で4GB倍数のインクリメント | 処理を中断（既知のバグ回避） |

## 備考

- VLF作成アルゴリズムはSQL Server 2014で変更されています
- SQL Server 2012未満では4GBの倍数での増加に既知のバグあり（MBで増加して回避）
- ShrinkLogFileはSimpleリカバリモデルでは使用不可
- ディスク空き容量検証はSQL Server 2005ではログファイルのドライブで実行不可
- SupportsShouldProcessを使用してWhatIf/Confirmに対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Expand-DbaDbLogFile.ps1 | `public/Expand-DbaDbLogFile.ps1` | 出力PSCustomObject構造（行510-523） |
| 1-2 | Expand-DbaDbLogFile.ps1 | `public/Expand-DbaDbLogFile.ps1` | パラメーター定義（行166-189） |

**読解のコツ**: このコマンドはSupportsShouldProcessを使用しているため、WhatIfパラメーターで実行内容を事前確認できます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Expand-DbaDbLogFile.ps1 | `public/Expand-DbaDbLogFile.ps1` | 関数定義全体（行1-533） |

**主要処理フロー**:
1. **行191-227**: beginブロックで初期化と接続
2. **行254-268**: データベースフィルタリングとログファイル特定
3. **行284-337**: ディスク空き容量検証
4. **行346-373**: SQL Serverバージョンに応じたインクリメントサイズ計算
5. **行377-443**: ログファイル縮小処理
6. **行459-499**: チャンク単位でのログファイル拡張
7. **行507-523**: 結果出力

#### Step 3: バージョン別インクリメント計算を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Expand-DbaDbLogFile.ps1 | `public/Expand-DbaDbLogFile.ps1` | SQL 2012+のswitch文（行347-355） |
| 3-2 | Expand-DbaDbLogFile.ps1 | `public/Expand-DbaDbLogFile.ps1` | SQL 2008R2以前のswitch文（行359-367） |

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

```
Expand-DbaDbLogFile
    │
    ├─ Connect-DbaInstance
    │
    ├─ Test-DbaPath (バックアップディレクトリ検証)
    │
    ├─ Resolve-DbaComputerName
    │
    ├─ Get-DbaDiskSpace (ディスク空き容量確認)
    │
    ├─ Measure-DbaDbVirtualLogFile (VLF数取得)
    │
    ├─ [縮小オプション使用時]
    │      ├─ New-Object Microsoft.SqlServer.Management.Smo.Backup
    │      └─ $logfile.Shrink()
    │
    └─ $logfile.Alter() (ログファイル拡張)
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server
                           │
TargetLogSize ───▶ インクリメント計算
                           │
ShrinkLogFile ───▶ [縮小処理]
                    ├─ TLogバックアップ
                    └─ Shrink
                           │
                           ▼
                    ループ拡張処理
                    ├─ logfile.size += increment
                    └─ logfile.Alter()
                           │
                           ▼
                      VLF数測定 ───▶ PSCustomObject
                           │
                           ▼
                      パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Expand-DbaDbLogFile.ps1 | `public/Expand-DbaDbLogFile.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Test-DbaPath.ps1 | `public/Test-DbaPath.ps1` | ソース | パス検証 |
| Get-DbaDiskSpace.ps1 | `public/Get-DbaDiskSpace.ps1` | ソース | ディスク空き容量取得 |
| Measure-DbaDbVirtualLogFile.ps1 | `public/Measure-DbaDbVirtualLogFile.ps1` | ソース | VLF数測定 |
| Resolve-DbaComputerName.ps1 | `internal/functions/Resolve-DbaComputerName.ps1` | ソース | コンピューター名解決 |
