# 機能設計書 651-Set-DbaDbFileGrowth

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Set-DbaDbFileGrowth` 関数の機能設計を記述するものである。本機能はSQL Serverデータベースのデータファイルおよびログファイルの自動拡張設定を、パーセンテージベースから固定サイズに変更するためのコマンドレットである。

### 本機能の処理概要

**業務上の目的・背景**：
SQL Serverのデフォルト自動拡張設定はパーセンテージベースであり、データベースが大きくなるにつれて拡張量が指数関数的に増加する。これにより、予測不能な成長パターン、ストレージの断片化、ディスク容量の急速な消費といった問題が発生する可能性がある。固定サイズ（デフォルト64MB）の自動拡張設定に変更することで、ファイル拡張の制御性を高め、パフォーマンスへの悪影響を軽減できる。

**機能の利用シーン**：
- 新規SQL Server環境のストレージベストプラクティス適用時
- 既存環境のパフォーマンスチューニング時
- データベースファイルの成長パターンを予測可能にしたい場合
- ストレージ管理ポリシーの一括適用時

**主要な処理内容**：
1. SQL Serverインスタンスへの接続とデータベースオブジェクトの取得
2. 対象ファイルタイプ（データファイル、ログファイル、または両方）の特定
3. ALTER DATABASE文の生成と実行による自動拡張設定の変更
4. 変更後のファイル設定情報の取得と出力

**関連システム・外部連携**：
- SQL Server Management Objects (SMO) を介したデータベース操作
- T-SQL ALTER DATABASE文によるファイル設定変更
- Get-DbaDatabase コマンドレットとの連携（パイプライン入力）
- Get-DbaDbFileGrowth コマンドレットによる変更後の設定確認

**権限による制御**：
対象データベースに対するALTER権限、またはデータベース所有者（db_owner）もしくはサーバー管理者（sysadmin）権限が必要である。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI (PowerShell) | 主画面 | コマンドライン実行による設定変更 |

## 機能種別

データ更新処理（UPDATE）/ 設定変更処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | string[] | No | 対象データベース名 | SqlInstanceと併用時必須 |
| GrowthType | string | No | 拡張サイズの単位（デフォルト: MB） | KB, MB, GB, TBのいずれか |
| Growth | int | No | 拡張サイズの数値（デフォルト: 64） | 正の整数 |
| FileType | string | No | 対象ファイルタイプ（デフォルト: All） | All, Data, Logのいずれか |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプラインからのデータベースオブジェクト | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドラインからの直接入力
- Get-DbaDatabase コマンドレットからのパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| MaxSize | DbaSize | ファイルの最大サイズ |
| GrowthType | string | 拡張タイプ（Percent または kb） |
| Growth | int | 拡張サイズ |
| File | string | ファイルの論理名 |
| FileName | string | OSファイルパス |
| State | string | ファイルの状態 |

### 出力先

PowerShellパイプライン（コンソール出力、変数格納、または後続コマンドへのパイプ）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ Database または InputObject が指定されているか確認
   └─ Database 指定時に SqlInstance が必須

2. データベースオブジェクト取得
   └─ SqlInstance 指定時: Get-DbaDatabase で取得
   └─ InputObject 指定時: パイプライン入力を使用

3. 各データベースに対するファイル処理
   └─ FileType に応じて LogFiles と/または FileGroups.Files を取得

4. 各ファイルの自動拡張設定変更
   └─ ALTER DATABASE 文の生成
   └─ クエリ実行
   └─ データベースとサーバーのリフレッシュ
   └─ Get-DbaDbFileGrowth による変更後設定の取得と出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Database/InputObject指定?}
    B -->|No| C[エラー: 必須パラメータ不足]
    B -->|Yes| D{SqlInstance指定?}
    D -->|Yes| E[Get-DbaDatabase実行]
    D -->|No| F[InputObjectを使用]
    E --> G[各データベースをループ]
    F --> G
    G --> H{FileType判定}
    H -->|Log/All| I[LogFiles取得]
    H -->|Data/All| J[FileGroups.Files取得]
    I --> K[各ファイルをループ]
    J --> K
    K --> L[ALTER DATABASE文生成]
    L --> M[クエリ実行]
    M --> N[DB/Serverリフレッシュ]
    N --> O[Get-DbaDbFileGrowth実行]
    O --> P[結果出力]
    P --> Q{次のファイル?}
    Q -->|Yes| K
    Q -->|No| R{次のDB?}
    R -->|Yes| G
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルト拡張サイズ | 拡張サイズ未指定時は64MBを適用 | Growthパラメータ未指定時 |
| BR-002 | 対象ファイルタイプ | FileTypeにより処理対象ファイルを決定 | 常時 |
| BR-003 | アクセス可能DB制限 | IsAccessibleプロパティがTrueのDBのみ処理 | SqlInstance経由でDB取得時 |

### 計算ロジック

- 自動拡張設定値: `FILEGROWTH = {Growth}{GrowthType}` の形式でALTER DATABASE文に組み込む

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイル設定変更 | sys.master_files | UPDATE（間接） | ALTER DATABASE MODIFY FILEによるファイル設定変更 |

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

#### sys.master_files（間接的な更新）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | growth | 指定されたGrowth値をKB単位で保存 | ALTER DATABASE経由 |
| UPDATE | is_percent_growth | 0（固定サイズ拡張） | ALTER DATABASE経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータエラー | Database/InputObject両方未指定 | Stop-Functionでエラーメッセージ表示 |
| - | パラメータエラー | Database指定時にSqlInstance未指定 | Stop-Functionでエラーメッセージ表示 |
| - | 接続エラー | SQL Serverへの接続失敗 | Stop-Function with -Continue |
| - | 実行エラー | ALTER DATABASE文の実行失敗 | Stop-Function with -Continue |

### リトライ仕様

自動リトライは実装されていない。エラー発生時は該当ファイルをスキップして次のファイルの処理を継続する。

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

- 各ALTER DATABASE文は個別のトランザクションとして実行される
- ファイル単位で即座にコミットされる
- ロールバック機能は提供されない（設定変更の取り消しには再度コマンド実行が必要）

## パフォーマンス要件

- 通常のファイル設定変更は即座に完了する
- 多数のデータベース/ファイルを処理する場合、ループ内でGet-DbaDbFileGrowthが繰り返し呼び出されるため、処理時間が増加する可能性がある

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

- SQL Serverへの認証はWindows認証またはSQL認証をサポート
- SqlCredentialパラメータによるセキュアな資格情報の受け渡し
- 対象データベースに対するALTER権限が必要
- WhatIf/Confirmパラメータによる事前確認機能

## 備考

- SMO経由での設定変更で問題が発生したため、T-SQL（ALTER DATABASE文）を直接使用している
- パイプライン出力により、処理結果を即座に確認可能

---

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

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

### 推奨読解順序

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

まず、入出力で使用されるデータ構造を理解することが重要である。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaDbFileGrowth.ps1 | `public/Set-DbaDbFileGrowth.ps1` | 104-116行目: パラメータ定義でInputObjectがSMO Databaseオブジェクトを受け取ることを確認 |

**読解のコツ**: PowerShellの`[Microsoft.SqlServer.Management.Smo.Database[]]`型は、SQL Server Management Objectsのデータベースオブジェクト配列を表す。

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

処理の起点となる関数構造を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Set-DbaDbFileGrowth.ps1 | `public/Set-DbaDbFileGrowth.ps1` | 1行目: 関数定義の開始 |
| 2-2 | Set-DbaDbFileGrowth.ps1 | `public/Set-DbaDbFileGrowth.ps1` | 103行目: CmdletBindingでSupportsShouldProcessを有効化 |

**主要処理フロー**:
1. **117行目**: processブロック開始
2. **118-126行目**: パラメータ検証（Test-Bound使用）
3. **128-130行目**: SqlInstance指定時のデータベース取得
4. **132-158行目**: メイン処理ループ

#### Step 3: ファイル取得ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbFileGrowth.ps1 | `public/Set-DbaDbFileGrowth.ps1` | 134-140行目: FileTypeに応じたファイル取得ロジック |

**主要処理フロー**:
- **135-136行目**: Log/All指定時はdb.LogFilesを取得
- **138-139行目**: Data/All指定時はdb.FileGroups.Filesを取得

#### Step 4: ALTER DATABASE実行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Set-DbaDbFileGrowth.ps1 | `public/Set-DbaDbFileGrowth.ps1` | 142-157行目: ファイル単位の設定変更処理 |

**主要処理フロー**:
- **143行目**: ShouldProcess確認
- **146行目**: ALTER DATABASE文の生成
- **148行目**: クエリ実行
- **149-150行目**: データベースとサーバーのリフレッシュ
- **152行目**: Get-DbaDbFileGrowth呼び出しで結果出力

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

```
Set-DbaDbFileGrowth
    │
    ├─ Test-Bound（パラメータ検証）
    │
    ├─ Stop-Function（エラー処理）
    │
    ├─ Get-DbaDatabase（SqlInstance指定時）
    │      └─ Connect-DbaInstance
    │
    ├─ Database.Query()（ALTER DATABASE実行）
    │
    ├─ Database.Refresh()（オブジェクトリフレッシュ）
    │
    ├─ Server.Refresh()（サーバーリフレッシュ）
    │
    └─ Get-DbaDbFileGrowth（変更後の設定取得）
```

### データフロー図

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

SqlInstance ────┐
                │
Database ───────┤
                ├──▶ Get-DbaDatabase ──▶ Database Objects
SqlCredential ──┤
                │
InputObject ────┘
                          │
                          ▼
                   FileType判定
                          │
              ┌───────────┴───────────┐
              ▼                       ▼
         LogFiles              FileGroups.Files
              │                       │
              └───────────┬───────────┘
                          │
                          ▼
                  ALTER DATABASE生成
                          │
                          ▼
                  Database.Query()
                          │
                          ▼
               Get-DbaDbFileGrowth ──────▶ PSCustomObject
                                           (ファイル設定情報)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Set-DbaDbFileGrowth.ps1 | `public/Set-DbaDbFileGrowth.ps1` | ソース | メイン機能実装 |
| Get-DbaDbFileGrowth.ps1 | `public/Get-DbaDbFileGrowth.ps1` | ソース | 変更後設定取得用 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
