# 機能設計書 115-Get-DbaDefaultPath

## 概要

本ドキュメントは、SQL Serverのデフォルトファイルパス（データ、ログ、バックアップ、エラーログ）を取得するための機能設計書である。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverは新しいデータベースファイルやバックアップファイルを作成する際、明示的にパスが指定されない場合はデフォルトパスを使用する。容量計画、自動化されたデータベースプロビジョニング、環境標準化の監査において、これらのパス情報は不可欠である。本機能は、SMOプロパティ、サーバープロパティ関数、システムデータベース情報を組み合わせて、確実にデフォルトパスを特定する。

**機能の利用シーン**：
- データベース自動作成スクリプトでのパス指定
- 容量計画とディスク配置の確認
- 複数インスタンス間のパス構成比較
- バックアップスクリプトでのデフォルトパス参照
- 環境構成ドキュメントの自動生成

**主要な処理内容**：
1. 対象SQL Serverインスタンスへ接続
2. SMOのDefaultFile/DefaultLogプロパティを取得
3. プロパティが空の場合、SERVERPROPERTYクエリでフォールバック
4. それでも取得できない場合、modelデータベースのファイルパスから推測
5. 最終フォールバックとしてmaster DBパスを使用
6. バックアップパスとエラーログパスを取得して結果を返却

**関連システム・外部連携**：SMOサーバーオブジェクト、SERVERPROPERTY関数、modelデータベースのファイル情報を使用。

**権限による制御**：サーバーレベルの設定読み取り権限が必要。modelデータベースへのアクセス権が必要（フォールバック時）。

## 関連画面

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

## 機能種別

データ参照 / 構成情報取得

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス（パイプライン可） | 接続可能なインスタンス名 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | 有効なWindows/SQL認証資格情報 |
| EnableException | switch | No | 例外を発生させるかどうか | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー入力またはパイプライン（必須）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverサービス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名（DomainInstanceName） |
| Data | string | データファイルのデフォルトパス |
| Log | string | ログファイルのデフォルトパス |
| Backup | string | バックアップファイルのデフォルトパス |
| ErrorLog | string | エラーログファイルのパス |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. processブロック開始
   └─ 各SqlInstanceについてループ処理
      ├─ 1.1 Connect-DbaInstance で接続（AzureUnsupported）
      ├─ 1.2 データパス取得シーケンス
      │      ├─ $server.DefaultFile プロパティ確認
      │      ├─ 空の場合: SERVERPROPERTY('InstanceDefaultDataPath') クエリ
      │      ├─ DBNullの場合: model DBのFileGroups[0].Files[0]から取得
      │      └─ それでも空: MasterDbPath使用
      ├─ 1.3 ログパス取得シーケンス
      │      ├─ $server.DefaultLog プロパティ確認
      │      ├─ 空の場合: SERVERPROPERTY('InstanceDefaultLogPath') クエリ
      │      ├─ DBNullの場合: model DBのLogFilesから取得
      │      └─ それでも空: MasterDbLogPath使用
      ├─ 1.4 パスの正規化（Trim、末尾バックスラッシュ除去）
      └─ 1.5 結果オブジェクト作成（Backup、ErrorLogを含む）
2. エラー処理
   └─ 接続失敗時は Stop-Function で次のインスタンスへ
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstanceをループ}
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function]
    E --> B
    D -->|Yes| F[$server.DefaultFile取得]
    F --> G{空?}
    G -->|No| H[dataPath確定]
    G -->|Yes| I[SERVERPROPERTY クエリ]
    I --> J{DBNull?}
    J -->|No| H
    J -->|Yes| K[model DB FileGroups取得]
    K --> L{空?}
    L -->|No| H
    L -->|Yes| M[MasterDbPath使用]
    M --> H
    H --> N[$server.DefaultLog取得]
    N --> O{空?}
    O -->|No| P[logPath確定]
    O -->|Yes| Q[SERVERPROPERTY クエリ]
    Q --> R{DBNull?}
    R -->|No| P
    R -->|Yes| S[model DB LogFiles取得]
    S --> T{空?}
    T -->|No| P
    T -->|Yes| U[MasterDbLogPath使用]
    U --> P
    P --> V[パス正規化]
    V --> W[PSCustomObject出力]
    W --> B
    B --> X[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Azure非対応 | Azure SQL Databaseは対象外 | 常時（AzureUnsupported） |
| BR-002 | フォールバック階層 | SMO → SERVERPROPERTY → model DB → master DB | DefaultFile/Log取得時 |
| BR-003 | パス正規化 | 末尾のスペースとバックスラッシュを除去 | 常時 |

### 計算ロジック

特になし。パス情報の取得と正規化のみ。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロパティ取得 | - | SMOプロパティ | DefaultFile、DefaultLog、BackupDirectory、ErrorlogPath |
| フォールバッククエリ | - | SERVERPROPERTY | InstanceDefaultDataPath、InstanceDefaultLogPath |
| モデルDB参照 | sys.database_files | SELECT (SMO経由) | modelデータベースのファイルパス |

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

#### SMO サーバープロパティ

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| GET | DefaultFile | - | データファイルデフォルトパス |
| GET | DefaultLog | - | ログファイルデフォルトパス |
| GET | BackupDirectory | - | バックアップデフォルトパス |
| GET | ErrorlogPath | - | エラーログパス |

#### SERVERPROPERTY関数

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | InstanceDefaultDataPath | SERVERPROPERTYクエリ | SMOプロパティ空時 |
| SELECT | InstanceDefaultLogPath | SERVERPROPERTYクエリ | SMOプロパティ空時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | Stop-Function でエラー出力、次のインスタンスへ |

### リトライ仕様

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

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

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

## パフォーマンス要件

- 各インスタンスに対して最大3回のフォールバック処理
- SMOプロパティ取得は高速（キャッシュ済み）
- SERVERPROPERTYクエリは軽量

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

- サーバー構成情報（ファイルパス）が出力される
- SQL認証使用時は資格情報の安全な管理が必要
- ファイルパスからサーバーのディスク構成が推測可能

## 備考

- Set-DbaDefaultPath 関数で設定変更可能
- SQL Server 2012以降ではSERVERPROPERTYによる取得が推奨
- 古いバージョンではmodelデータベースからの推測が必要

---

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

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

### 推奨読解順序

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

本機能では出力が単純なPSCustomObjectである。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | 出力オブジェクトの構造（109-117行目） |

**読解のコツ**: 4つのパス（Data、Log、Backup、ErrorLog）を持つシンプルな構造。

#### Step 2: フォールバック階層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | データパス取得のフォールバック（79-90行目） |
| 2-2 | Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | ログパス取得のフォールバック（92-104行目） |

**主要処理フロー**:
1. **79行目**: $server.DefaultFile プロパティ取得
2. **80-82行目**: 空チェックとSERVERPROPERTYフォールバック
3. **84-86行目**: DBNullチェックとmodel DBフォールバック
4. **88-90行目**: 最終フォールバック（MasterDbPath）

#### Step 3: パス正規化を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | パス正規化処理（106-107行目） |

**主要処理フロー**:
- **106行目**: $dataPath.Trim().TrimEnd("\")
- **107行目**: $logPath.Trim().TrimEnd("\")

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

```
Get-DbaDefaultPath
    │
    ├─ Connect-DbaInstance (-AzureUnsupported)
    │
    ├─ $server.DefaultFile / $server.DefaultLog
    │
    ├─ $server.Query() [フォールバック]
    │      └─ SERVERPROPERTY('InstanceDefaultDataPath')
    │      └─ SERVERPROPERTY('InstanceDefaultLogPath')
    │
    ├─ Get-DbaDatabase [フォールバック]
    │      └─ model DBのFileGroups/LogFiles
    │
    ├─ $server.Information.MasterDbPath [最終フォールバック]
    │
    └─ PSCustomObject 出力
           ├─ Data
           ├─ Log
           ├─ Backup ($server.BackupDirectory)
           └─ ErrorLog ($server.ErrorlogPath)
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ $server

$server.DefaultFile ──┬── 成功 ──────────────────────────▶ Data
                      │
                      └── 空 ──▶ SERVERPROPERTY ──┬── 成功 ─▶ Data
                                                   │
                                                   └── DBNull ─▶ model DB ─▶ Data
                                                                     │
                                                                     └── 空 ─▶ MasterDbPath ─▶ Data

$server.DefaultLog ──┬── 成功 ──────────────────────────▶ Log
                     │
                     └── 空 ──▶ SERVERPROPERTY ──┬── 成功 ─▶ Log
                                                  │
                                                  └── DBNull ─▶ model DB ─▶ Log
                                                                    │
                                                                    └── 空 ─▶ MasterDbLogPath ─▶ Log

$server.BackupDirectory ─────────────────────────────────▶ Backup

$server.ErrorlogPath ────────────────────────────────────▶ ErrorLog
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | ソース | メイン関数の実装 |
| Set-DbaDefaultPath.ps1 | `public/Set-DbaDefaultPath.ps1` | ソース | 関連機能：デフォルトパス設定 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | modelデータベース取得（フォールバック用） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続機能 |
