# 機能設計書 112-Get-DbaDbSpace

## 概要

本ドキュメントは、SQL Serverデータベースファイルの空間使用状況を取得するための機能設計書である。データファイルおよびログファイルの使用量、空き容量、自動拡張設定などの詳細なメトリクスを提供する。

### 本機能の処理概要

**業務上の目的・背景**：データベースの容量管理は、SQL Server運用において最も重要な課題の一つである。ディスク容量の枯渇はサービス停止につながり、適切な容量計画なしには予期せぬ問題が発生する。本機能は、Glenn Berryの有名なDMVスクリプトをベースに、データベースファイルの空間使用状況を包括的に取得し、容量計画や監視を支援する。

**機能の利用シーン**：
- 定期的なデータベース容量監視
- 容量計画とトレンド分析
- ファイルサイズ上限に近づいているデータベースの特定
- 自動拡張設定の監査
- ディスク容量不足の予防的検出

**主要な処理内容**：
1. 対象データベースへ接続し、sys.database_filesとFILEPROPERTY関数を使用してファイル情報を取得
2. 各ファイルの使用量、空き容量、ファイルサイズを計算
3. 自動拡張設定（固定サイズまたはパーセンテージ）を取得
4. 最大サイズまでの残り容量を計算
5. dbasize型のオブジェクトとして結果を返却

**関連システム・外部連携**：SQL Server DMV（sys.database_files）およびFILEPROPERTY関数を使用。外部システムとの連携はない。

**権限による制御**：対象データベースへの読み取り権限が必要。sys.database_filesビューへのアクセス権が必要（通常はpublicロールで付与される）。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | PowerShellコマンドラインインターフェースのみ |

## 機能種別

データ参照（SELECT操作）/ 空間メトリクス取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス（パイプライン可） | 接続可能なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なWindows/SQL認証資格情報 |
| Database | string[] | No | 分析対象データベース名（ワイルドカード対応） | 存在するデータベース名 |
| ExcludeDatabase | string[] | No | 除外するデータベース名（ワイルドカード対応） | 存在するデータベース名 |
| IncludeSystemDBs | switch | No | 非推奨パラメータ（エラー発生） | - |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプライン経由でのデータベースオブジェクト | SMO Databaseオブジェクト |
| EnableException | switch | No | 例外を発生させるかどうか | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー入力またはパイプライン
- InputObject: Get-DbaDatabase からのパイプライン入力
- Database/ExcludeDatabase: フィルタリング条件

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| FileName | string | 論理ファイル名 |
| FileGroup | string | ファイルグループ名（ログファイルはnull） |
| PhysicalName | string | 物理ファイルパス |
| FileType | string | ファイル種別（ROWS/LOG） |
| UsedSpace | dbasize | 使用中の容量 |
| FreeSpace | dbasize | ファイル内の空き容量 |
| FileSize | dbasize | ファイルの合計サイズ |
| PercentUsed | int | 使用率（0-100） |
| AutoGrowth | dbasize | 自動拡張増分 |
| AutoGrowType | string | 自動拡張タイプ（MB/pct/Unknown） |
| SpaceUntilMaxSize | dbasize | 最大サイズまでの残り容量 |
| AutoGrowthPossible | dbasize | 自動拡張で追加可能な最大容量 |
| UnusableSpace | dbasize | 拡張後の使用不能領域 |

### 出力先

- PowerShellパイプライン（標準出力）
- PSCustomObject として返却

## 処理フロー

### 処理シーケンス

```
1. beginブロック: SQLクエリの定義
   └─ sys.database_files と FILEPROPERTY を結合したクエリを準備
2. processブロック開始
   ├─ 2.1 IncludeSystemDBs パラメータチェック
   │      └─ 指定されていたらStop-Functionでエラー終了
   ├─ 2.2 SqlInstance指定時: Get-DbaDatabase でデータベースを取得
   │      └─ Database/ExcludeDatabase フィルタを適用
   └─ 2.3 各データベースについてループ処理
          ├─ バージョンチェック（SQL Server 2000は非対応）
          ├─ データベースアクセス可能性チェック
          ├─ SQLクエリ実行
          └─ 結果をdbasize型に変換して出力
3. エラー処理
   └─ 失敗時は Stop-Function でメッセージ出力し次のDBへ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SQLクエリ定義]
    B --> C{IncludeSystemDBs?}
    C -->|Yes| D[Stop-Function エラー]
    D --> E[終了]
    C -->|No| F{SqlInstance指定?}
    F -->|Yes| G[Get-DbaDatabase]
    G --> H[InputObjectに追加]
    F -->|No| H
    H --> I{InputObjectをループ}
    I --> J{SQL 2000?}
    J -->|Yes| K[スキップ、警告出力]
    K --> I
    J -->|No| L{DBアクセス可能?}
    L -->|No| M[警告出力]
    M --> I
    L -->|Yes| N[SQLクエリ実行]
    N --> O[結果をdbasize変換]
    O --> P[PSCustomObject出力]
    P --> I
    I --> E
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SQL 2000非対応 | SQL Server 2000 はサポートしない | VersionMajor < 9 |
| BR-002 | IncludeSystemDBs非推奨 | このパラメータは削除予定。代わりにGet-DbaDatabase -IncludeSystem を使用 | 常時 |
| BR-003 | 無制限ファイルの扱い | max_size = -1 の場合、2TB (2147483648 MB) として計算 | 最大サイズ未設定時 |
| BR-004 | DBNull処理 | NULL値は0として扱う | UsedSpace, FreeSpace等がNULLの場合 |

### 計算ロジック

- **UsedSpace**: FILEPROPERTY(f.name, 'SpaceUsed') / 128.0 MB
- **FreeSpace**: (f.size - FILEPROPERTY(f.name, 'SpaceUsed')) / 128.0 MB
- **FileSize**: f.size / 128.0 MB
- **PercentUsed**: (SpaceUsed / size) * 100
- **SpaceUntilMaxSize**: max_size未設定時は2TB - 使用量、設定時はmax_size - 使用量
- **AutoGrowthPossible**: 複雑な計算ロジック（固定サイズ増分とパーセンテージ増分で異なる）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ファイル情報取得 | sys.database_files | SELECT | データベースファイルのメタデータを取得 |
| ファイルグループ情報取得 | sys.filegroups | SELECT (LEFT JOIN) | ファイルグループ名を取得 |

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

#### sys.database_files

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, physical_name, type_desc, size, growth, is_percent_growth, max_size, data_space_id | 全件 | FILEPROPERTY関数と組み合わせ |

#### sys.filegroups

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | name, data_space_id | LEFT JOIN on data_space_id | ログファイルはNULL |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バージョンエラー | SQL Server 2000 | Stop-Function でスキップ |
| - | アクセス不可 | データベースがOffline/Restoring等 | Write-Message で警告、スキップ |
| - | クエリエラー | SQLクエリ実行失敗 | Stop-Function でエラー出力、次のDBへ |
| - | パラメータエラー | IncludeSystemDBs 指定 | Stop-Function でエラー終了 |

### リトライ仕様

リトライ処理は実装されていない。エラー時は当該データベースをスキップして次を処理。

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

読み取り専用操作のため、トランザクション管理は不要。NOLOCK ヒントを使用。

## パフォーマンス要件

- 各データベースに対して1回のクエリを実行
- sys.database_filesは小さなシステムビューであり、高速に完了
- 大量のデータベースがある場合は並列処理を検討

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

- sys.database_filesへの読み取り権限が必要
- 機密情報（ファイルパス）が出力される
- SQL認証使用時は資格情報の安全な管理が必要

## 備考

- dbasize型により、出力値は.Bytes、.Kilobytes、.Megabytes、.Gigabytes、.Terabytesプロパティで変換可能
- Glenn Berry の DMVスクリプトをベースに開発
- SQL Server 2005以降で動作

---

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

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

### 推奨読解順序

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

本機能ではsys.database_filesシステムビューとFILEPROPERTY関数を使用する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | 出力がPSCustomObjectでdbasize型プロパティを含むことを確認 |

**読解のコツ**: dbasize型はdbatoolsのカスタム型で、バイト単位の値を保持し、各種単位への変換メソッドを提供する。

#### Step 2: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | beginブロックのSQLクエリ定義（117-167行目） |

**主要処理フロー**:
1. **118-121行目**: サーバープロパティとデータベース名の取得
2. **122-131行目**: ファイル基本情報（名前、パス、タイプ、サイズ）
3. **132行目**: max_size = -1 の場合の2TB変換
4. **133-163行目**: SpaceBeforeAutoGrow、SpaceBeforeMax、PossibleAutoGrowthMB、UnusableSpaceMBの複雑な計算
5. **165-167行目**: sys.database_files と sys.filegroups の結合

#### Step 3: 結果処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | processブロックの結果変換ロジック（192-238行目） |

**主要処理フロー**:
- **193-217行目**: DBNull値の0への変換処理
- **219-237行目**: PSCustomObjectの構築とdbasize型への変換

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

```
Get-DbaDbSpace
    │
    ├─ Get-DbaDatabase (SqlInstance指定時)
    │      └─ Connect-DbaInstance
    │
    └─ $db.ExecuteWithResults($sql)
           │
           └─ sys.database_files + sys.filegroups クエリ
                  │
                  └─ FILEPROPERTY() 関数呼び出し
```

### データフロー図

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

SqlInstance ───────▶ Get-DbaDatabase ───▶ InputObject
                            │
Database/Exclude ───────────┘

InputObject ───────▶ ExecuteWithResults ───▶ クエリ結果
                            │
                            ▼
                     DBNull → 0 変換
                            │
                            ▼
                     dbasize型変換
                            │
                            ▼
                     PSCustomObject ───▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | ソース | メイン関数の実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得のヘルパー関数 |
| dbasize.ps1 | `private/classes/dbasize.ps1` | ソース | dbasize型の定義（サイズ変換機能） |
| Get-DbaDbSpace.Tests.ps1 | `tests/Get-DbaDbSpace.Tests.ps1` | テスト | 単体テスト |
