# 画面設計書 62-空間・メモリ情報

## 概要

本ドキュメントは、dbatools PowerShell モジュールにおけるデータベース空間使用量・メモリ使用量・仮想ログファイル（VLF）情報の取得機能の設計仕様を定義する。SQL Server のストレージとメモリリソースの監視・分析に使用する機能群である。

### 本画面の処理概要

本機能群は、SQL Server のデータベースファイルの空間使用状況、バッファプールのメモリ消費状況、トランザクションログの VLF 情報を取得し、キャパシティプランニングやパフォーマンス分析に必要なデータを提供する。

**業務上の目的・背景**：DBA はデータベースのストレージ使用状況を定期的に監視し、ディスク容量不足を事前に検知する必要がある。また、メモリ消費の偏りや VLF の過剰な増加はパフォーマンス低下の原因となるため、これらの情報を収集・分析することで適切な容量計画とメンテナンス計画を立案できる。本機能群は、sys.database_files、sys.dm_os_buffer_descriptors、DBCC LOGINFO などを統合的に活用し、PowerShell から効率的にデータを収集できる。

**画面へのアクセス方法**：本機能は CLI として提供される。PowerShell コンソールから各コマンドを直接呼び出す。Get-DbaDatabase からのパイプライン入力も可能。

**主要な操作・処理内容**：
1. `Get-DbaDbSpace` - データベースファイルの空間使用量・自動拡張設定・最大サイズまでの残容量を取得
2. `Get-DbaDbMemoryUsage` - バッファプール内のデータベース別・ページタイプ別メモリ消費量を取得
3. `Get-DbaDbVirtualLogFile` - トランザクションログの VLF 詳細情報（サイズ、オフセット、ステータス等）を取得
4. `Measure-DbaDbVirtualLogFile` - VLF の総数・アクティブ数・非アクティブ数をサマリー形式で取得

**画面遷移**：
- Get-DbaDatabase → Get-DbaDbSpace のパイプライン連携
- Get-DbaDbSpace → Where-Object でフィルタリングし、PercentUsed が高いファイルを抽出
- Measure-DbaDbVirtualLogFile → 高 VLF 数のデータベースを特定後、Expand-DbaDbLogFile で改善

**権限による表示制御**：データベースファイル情報の取得には対象データベースへのアクセス権限が必要。sys.dm_os_buffer_descriptors の参照には VIEW SERVER STATE 権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 112 | Get-DbaDbSpace | 主機能 | データベースファイル空間使用量の取得 |
| 406 | Get-DbaDbMemoryUsage | 補助機能 | バッファプールメモリ使用量の取得 |
| 637 | Get-DbaDbVirtualLogFile | 補助機能 | VLF 詳細情報の取得 |
| 644 | Measure-DbaDbVirtualLogFile | 補助機能 | VLF 数のサマリー測定 |

## 画面種別

CLI（コマンドラインインターフェース）/ 一覧出力

## URL/ルーティング

PowerShell コマンドレットとして呼び出し。URL は存在しない。

```powershell
# 各コマンドの呼び出し例
Get-DbaDbSpace -SqlInstance <インスタンス名>
Get-DbaDbMemoryUsage -SqlInstance <インスタンス名> -IncludeSystemDb
Get-DbaDbVirtualLogFile -SqlInstance <インスタンス名> -Database <データベース名>
Measure-DbaDbVirtualLogFile -SqlInstance <インスタンス名>
```

## 入出力項目

### 共通入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス |
| SqlCredential | PSCredential | No | 認証情報（Windows認証以外の場合） |
| Database | string[]/object[] | No | 対象データベース（ワイルドカード可） |
| ExcludeDatabase | string[]/object[] | No | 除外データベース |
| EnableException | switch | No | 例外処理を有効化 |

### Get-DbaDbSpace 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| InputObject | Database[] | No | Get-DbaDatabase からのパイプライン入力 |
| IncludeSystemDBs | switch | No | 非推奨（エラー終了） |

### Get-DbaDbMemoryUsage 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| IncludeSystemDb | switch | No | システムデータベースを含める |

### Get-DbaDbVirtualLogFile / Measure-DbaDbVirtualLogFile 固有パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|---|------|------|
| IncludeSystemDBs | switch | No | システムデータベースを含める |

## 表示項目

### Get-DbaDbSpace 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| 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） |
| SpaceUntilMaxSize | dbasize | 最大サイズまでの残容量 |
| AutoGrowthPossible | dbasize | 自動拡張可能な最大追加容量 |
| UnusableSpace | dbasize | 自動拡張後の利用不可領域 |

### Get-DbaDbMemoryUsage 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| PageType | string | ページタイプ |
| PageCount | int | ページ数（非表示デフォルト） |
| Size | DbaSize | メモリ使用量（MB） |
| PercentUsed | int | バッファプール使用率（0-100） |

### Get-DbaDbVirtualLogFile 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| RecoveryUnitId | int | リカバリユニットID |
| FileId | int | トランザクションログファイルID |
| FileSize | bigint | VLF サイズ（バイト） |
| StartOffset | bigint | VLF 開始オフセット（バイト） |
| FSeqNo | bigint | VLF シーケンス番号 |
| Status | int | VLF ステータス（0=未使用、1=アクティブ、2=回復可能） |
| Parity | int | パリティ値 |
| CreateLsn | decimal | VLF 作成時の LSN |

### Measure-DbaDbVirtualLogFile 出力

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | サーバーコンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| Total | int | VLF 総数（デフォルト表示） |
| TotalCount | int | VLF 総数（Total の重複） |
| Inactive | int | 非アクティブ VLF 数 |
| Active | int | アクティブ VLF 数 |
| LogFileName | string | ログファイル名（カンマ区切り） |
| LogFileGrowth | string | ログファイル拡張増分（カンマ区切り） |
| LogFileGrowthType | string | ログファイル拡張タイプ（カンマ区切り） |

## イベント仕様

### 1-Get-DbaDbSpace 実行

1. SqlInstance または InputObject からデータベースオブジェクトを取得
2. IncludeSystemDBs が指定された場合はエラー終了（非推奨パラメータ）
3. SQL Server 2000 の場合はエラー終了（非サポート）
4. sys.database_files と FILEPROPERTY を組み合わせたクエリを実行
5. UsedSpaceMB、FreeSpaceMB 等を計算し、DBNull 処理を実施
6. dbasize オブジェクトに変換して PSCustomObject として出力

### 2-Get-DbaDbMemoryUsage 実行

1. SqlInstance に Connect-DbaInstance で接続（MinimumVersion 9 以上）
2. sys.dm_os_buffer_descriptors と sys.dm_os_performance_counters をクエリ
3. Database、ExcludeDatabase パラメータでフィルタリング
4. IncludeSystemDb 未指定時はシステムデータベースをスキップ
5. PageType 別にメモリ使用量を集計
6. Select-DefaultView で PageCount を非表示に設定して出力

### 3-Get-DbaDbVirtualLogFile 実行

1. SqlInstance に接続
2. IsAccessible なデータベースをフィルタリング
3. 各データベースで DBCC LOGINFO を実行
4. 結果を PSCustomObject として出力

### 4-Measure-DbaDbVirtualLogFile 実行

1. SqlInstance に接続
2. Database、ExcludeDatabase でフィルタリング
3. Get-DbaDbVirtualLogFile を呼び出して VLF 情報を取得
4. Get-DbaDbFile でログファイル情報を取得
5. Status=2 をアクティブ、Status=0 を非アクティブとしてカウント
6. サマリー情報を Select-DefaultView で出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaDbSpace | sys.database_files, sys.filegroups | SELECT | ファイル情報読み取り |
| Get-DbaDbMemoryUsage | sys.dm_os_buffer_descriptors, sys.dm_os_performance_counters | SELECT | メモリ使用情報読み取り |
| Get-DbaDbVirtualLogFile | DBCC LOGINFO | SELECT | VLF 情報読み取り |
| Measure-DbaDbVirtualLogFile | 上記 + sys.database_files | SELECT | VLF サマリー情報読み取り |

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

本機能群は読み取り専用のため、データベース更新は発生しない。

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| - | エラー | "IncludeSystemDBs will be removed. Please pipe in filtered results from Get-DbaDatabase instead." | Get-DbaDbSpace で IncludeSystemDBs 指定時 |
| - | エラー | "SQL Server 2000 not supported. {server} skipped." | SQL Server 2000 接続時 |
| - | 警告 | "{db} is not accessible." | データベースアクセス不可 |
| - | エラー | "Failure" | 接続エラー |
| - | エラー | "Issue collecting data" | データ収集エラー |
| - | エラー | "Unable to query {db} on {instance}." | クエリ実行エラー |

## 例外処理

| 例外条件 | ハンドリング | ユーザーへのフィードバック |
|---------|-------------|-------------------------|
| 接続エラー | Stop-Function -Continue | "Failure" メッセージと ConnectionError カテゴリ |
| SQL Server 2000 | Stop-Function -Continue | "SQL Server 2000 not supported." |
| データベースアクセス不可 | Write-Message -Level Warning + continue | "{db} is not accessible." |
| DBNull 値 | 0 に置換 | 正常出力（0 値） |
| MinimumVersion 不足 | Connect-DbaInstance でエラー | 接続エラーとして処理 |

## 備考

- dbasize 型は .Bytes、.Kilobytes、.Megabytes、.Gigabytes、.Terabytes プロパティで単位変換可能
- VLF 数が 50-100 を超える場合はパフォーマンス問題の可能性あり
- Get-DbaDbSpace の IncludeSystemDBs は非推奨。Get-DbaDatabase -IncludeSystem | Get-DbaDbSpace を使用
- ResourceDb（database_id=32767）は特別なシステムデータベースとして処理

---

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

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

### 推奨読解順序

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

dbasize 型と出力 PSCustomObject の構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | 行 219-237: 出力プロパティと dbasize への変換 |

**読解のコツ**: [dbasize] 型キャストにより、サイズ値が自動的に適切な単位で表示される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | 行 106-116: パラメータ定義と ValueFromPipeline |

**主要処理フロー**:
1. **行 117-168**: begin ブロックで SQL クエリを定義
2. **行 170-177**: process ブロックで InputObject を構築
3. **行 179-242**: 各データベースに対してクエリ実行と結果整形

#### Step 3: SQL クエリロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | 行 118-167: sys.database_files と FILEPROPERTY を使用した空間計算 |
| 3-2 | Get-DbaDbMemoryUsage.ps1 | `public/Get-DbaDbMemoryUsage.ps1` | 行 104-121: sys.dm_os_buffer_descriptors クエリ |

**主要処理フロー**:
- **行 126-127 (Space)**: FILEPROPERTY('SpaceUsed') で使用領域を取得
- **行 132-137**: max_size = -1 は無制限を意味し、2147483648（2TB）を最大値として計算
- **行 138-153**: 自動拡張による拡張可能領域の複雑な計算（固定サイズ拡張とパーセント拡張の両方をサポート）

#### Step 4: VLF 情報取得ロジック

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaDbVirtualLogFile.ps1 | `public/Get-DbaDbVirtualLogFile.ps1` | 行 132: DBCC LOGINFO の実行 |
| 4-2 | Measure-DbaDbVirtualLogFile.ps1 | `public/Measure-DbaDbVirtualLogFile.ps1` | 行 133-137: Get-DbaDbVirtualLogFile の呼び出しと集計 |

**主要処理フロー**:
- **行 136-137 (Measure)**: Status=2 がアクティブ、Status=0 が非アクティブ
- **行 146-147**: Count が null の場合（1件のみ）の処理

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

```
Get-DbaDbSpace
    |
    +-- Get-DbaDatabase (InputObject 取得)
    |
    +-- $db.ExecuteWithResults($sql)
    |       |
    |       +-- sys.database_files
    |       +-- sys.filegroups
    |       +-- FILEPROPERTY()
    |
    +-- [dbasize] 変換
    |
    +-- [PSCustomObject] 出力

Measure-DbaDbVirtualLogFile
    |
    +-- Connect-DbaInstance
    |
    +-- Get-DbaDbVirtualLogFile (VLF 詳細取得)
    |       |
    |       +-- DBCC LOGINFO
    |
    +-- Get-DbaDbFile (ログファイル情報)
    |
    +-- Status によるアクティブ/非アクティブ集計
    |
    +-- Select-DefaultView
```

### データフロー図

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

SqlInstance    ------>  Connect-DbaInstance
                              |
Database       ------>  Get-DbaDatabase
                              |
                        sys.database_files クエリ
                              |
                        FILEPROPERTY 計算
                              |
                        DBNull 処理
                              |
                        [dbasize] 変換  ---------->  PSCustomObject
                                                      (UsedSpace, FreeSpace,
                                                       FileSize, PercentUsed...)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbSpace.ps1 | `public/Get-DbaDbSpace.ps1` | ソース | データベースファイル空間使用量取得 |
| Get-DbaDbMemoryUsage.ps1 | `public/Get-DbaDbMemoryUsage.ps1` | ソース | バッファプールメモリ使用量取得 |
| Get-DbaDbVirtualLogFile.ps1 | `public/Get-DbaDbVirtualLogFile.ps1` | ソース | VLF 詳細情報取得 |
| Measure-DbaDbVirtualLogFile.ps1 | `public/Measure-DbaDbVirtualLogFile.ps1` | ソース | VLF 数サマリー取得 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | ソース | データベースファイル情報取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server 接続 |
