# 機能設計書 188-New-DbaDatabase

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおける `New-DbaDatabase` コマンドレットの機能設計書である。このコマンドレットは、カスタマイズ可能なファイルレイアウトと成長設定を持つ新しいSQL Serverデータベースを作成する機能を提供する。

### 本機能の処理概要

本機能は、ファイル配置、サイズ設定、成長設定を完全に制御してSQL Serverインスタンスに新しいデータベースを作成する。手動でT-SQL CREATE DATABASE文を実行する代わりに、データベース作成に対する構造化されたアプローチを提供し、ベストプラクティスが組み込まれている。固定MB単位の成長設定を自動的に構成し、本番環境での暴走オートグロースの問題を防ぐ。

**業務上の目的・背景**：データベースの作成は日常的な運用タスクであるが、適切なファイルサイズ、成長設定、配置を手動で構成するのは煩雑でエラーが発生しやすい。本機能により、一貫性のある標準化されたデータベース作成を実現し、パーセント成長による問題を回避するベストプラクティスを強制する。

**機能の利用シーン**：
- 新規データベースの作成
- 標準化されたファイル構成での一括データベース作成
- 開発環境用のテストデータベース作成
- パフォーマンス最適化のためのセカンダリファイルグループ設定
- 複数インスタンスへの同時データベース作成

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. 照合順序の検証（指定時）
3. データファイルパスとログファイルパスの決定
4. PRIMARYファイルグループとデータファイルの作成
5. トランザクションログファイルの作成
6. セカンダリファイルグループとファイルの作成（指定時）
7. データベース作成の実行
8. 所有者の設定（指定時）
9. デフォルトファイルグループの設定（指定時）

**関連システム・外部連携**：SQL Server SMO、ファイルシステム

**権限による制御**：CREATE DATABASE権限またはsysadminサーバーロールが必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 18 | データベース管理 | 主機能 | データベースの新規作成 |

## 機能種別

CRUD操作（データベースの作成）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | 必須、パイプラインから入力可能 |
| SqlCredential | PSCredential | No | 代替認証資格情報 | - |
| Name | string[] | No | 作成するデータベース名 | 未指定時はランダム名 |
| Collation | string | No | データベース照合順序 | インスタンスで有効な照合順序 |
| RecoveryModel | string | No | 復旧モデル | ValidateSet: Simple/Full/BulkLogged |
| Owner | string | No | データベース所有者 | 存在するログイン |
| DataFilePath | string | No | データファイルの配置ディレクトリ | 未指定時はインスタンスデフォルト |
| LogFilePath | string | No | ログファイルの配置ディレクトリ | 未指定時はインスタンスデフォルト |
| PrimaryFilesize | int32 | No | プライマリファイルの初期サイズ（MB） | model DBより小さい場合はmodel使用 |
| PrimaryFileGrowth | int32 | No | プライマリファイルの成長単位（MB） | - |
| PrimaryFileMaxSize | int32 | No | プライマリファイルの最大サイズ（MB） | - |
| LogSize | int32 | No | ログファイルの初期サイズ（MB） | - |
| LogGrowth | int32 | No | ログファイルの成長単位（MB） | - |
| LogMaxSize | int32 | No | ログファイルの最大サイズ（MB） | - |
| SecondaryFilesize | int32 | No | セカンダリファイルの初期サイズ（MB） | - |
| SecondaryFileGrowth | int32 | No | セカンダリファイルの成長単位（MB） | - |
| SecondaryFileMaxSize | int32 | No | セカンダリファイルの最大サイズ（MB） | - |
| SecondaryFileCount | int32 | No | セカンダリファイルグループのファイル数 | - |
| DefaultFileGroup | string | No | デフォルトファイルグループ | ValidateSet: Primary/Secondary |
| DataFileSuffix | string | No | データファイル名のサフィックス | - |
| LogFileSuffix | string | No | ログファイル名のサフィックス | デフォルト'_log' |
| SecondaryDataFileSuffix | string | No | セカンダリファイルグループのサフィックス | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- ユーザー入力（パラメータ指定）
- パイプライン入力（SqlInstance）
- model データベース（デフォルトサイズ設定）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Name | string | 作成されたデータベース名 |
| Status | string | データベースステータス |
| IsAccessible | bool | アクセス可能かどうか |
| RecoveryModel | string | 復旧モデル |
| LogReuseWaitStatus | string | ログ再利用待機状態 |
| Size | decimal | データベースサイズ（MB） |
| Compatibility | int | 互換性レベル |
| Collation | string | 照合順序 |
| Owner | string | 所有者 |
| Encrypted | bool | 暗号化状態 |
| LastFullBackup | datetime | 最終フルバックアップ日時 |
| LastDiffBackup | datetime | 最終差分バックアップ日時 |
| LastLogBackup | datetime | 最終ログバックアップ日時 |

### 出力先

PowerShellパイプライン（Microsoft.SqlServer.Management.Smo.Databaseオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. beginブロック処理
   └─ 詳細設定パラメータの検出（advancedconfig判定）
2. processブロック処理
   └─ 各SqlInstanceを処理
3. インスタンス接続
   └─ Connect-DbaInstance
4. SQL Server 2000チェック
   └─ 詳細設定はSQL 2000で非対応
5. 照合順序検証
   └─ Get-DbaAvailableCollationで確認
6. データベース名決定
   └─ 未指定時はrandom-{番号}
7. ファイルパス決定
   └─ Get-DbaDefaultPathでデフォルト取得
8. ディレクトリ作成
   └─ New-DbaDirectoryで存在しない場合作成
9. データベースオブジェクト作成
   └─ SMO Databaseオブジェクト
10. 詳細設定（advancedconfig）
    └─ PRIMARYファイルグループ作成
    └─ プライマリデータファイル作成
    └─ トランザクションログ作成
    └─ セカンダリファイルグループ作成（指定時）
11. データベース作成
    └─ $newdb.Create()
12. 所有者設定
    └─ SetOwner()
13. デフォルトファイルグループ設定
    └─ SetDefaultFileGroup()
14. 結果取得
    └─ Get-DbaDatabase
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{詳細設定パラメータ?}
    B -->|Yes| C[advancedconfig = true]
    B -->|No| D[advancedconfig = false]
    C --> E[各SqlInstanceを処理]
    D --> E
    E --> F[Connect-DbaInstance]
    F --> G{SQL 2000 + 詳細設定?}
    G -->|Yes| H[Stop-Function]
    G -->|No| I{照合順序指定?}
    I -->|Yes| J[照合順序検証]
    I -->|No| K[パス決定]
    J --> K
    K --> L[ディレクトリ作成]
    L --> M[SMO Database作成]
    M --> N{advancedconfig?}
    N -->|Yes| O[ファイルグループ・ファイル設定]
    N -->|No| P[Create実行]
    O --> P
    P --> Q{Owner指定?}
    Q -->|Yes| R[SetOwner]
    Q -->|No| S{DefaultFileGroup=Secondary?}
    R --> S
    S -->|Yes| T[SetDefaultFileGroup]
    S -->|No| U[Get-DbaDatabase]
    T --> U
    U --> V[結果出力]
    V --> W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | SQL 2000制限 | 詳細設定オプションはSQL Server 2000で非対応 | VersionMajor=8 + advancedconfig時 |
| BR-002 | modelサイズ優先 | 指定サイズがmodelより小さい場合はmodelサイズを使用 | ファイルサイズ指定時 |
| BR-003 | 固定MB成長 | パーセント成長ではなく固定MB成長を使用 | FileGrowth指定時 |
| BR-004 | ログファイルサフィックス | デフォルトは'_log' | LogFileSuffix未指定時 |
| BR-005 | 既存DB確認 | 同名データベースが存在する場合はエラー | 常時 |

### 計算ロジック

| ファイルサイズ | 計算式 |
|---------------|--------|
| プライマリファイル | max(PrimaryFilesize * 1024, modeldev.Size) KB |
| ログファイル | max(LogSize * 1024, modellog.Size) KB |
| セカンダリファイル | max(SecondaryFilesize * 1024, modeldev.Size) KB |

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| DB作成 | master.sys.databases等 | INSERT | データベースメタデータの登録 |
| 照合順序確認 | sys.fn_helpcollations() | SELECT | 有効な照合順序の確認 |

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

#### master.sys.databases

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | database_id, name, collation_name等 | パラメータ値 | SMO経由で実行 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | 接続情報確認 |
| - | SQL 2000制限 | 詳細設定 + SQL 2000 | 詳細設定を使用しない |
| - | 照合順序不正 | 無効な照合順序指定 | 有効な照合順序を指定 |
| - | DB重複 | 同名データベースが存在 | 別名を使用 |
| - | ディレクトリ作成失敗 | パス作成権限なし | 権限確認またはパス変更 |

### リトライ仕様

リトライ処理は実装されていない。

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

SMO Create()メソッドは内部的にトランザクションを管理。

## パフォーマンス要件

- データベース作成時間はファイルサイズに依存
- インスタントファイル初期化が有効な場合はデータファイル作成が高速化

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

- CREATE DATABASE権限またはsysadminロールが必要
- ファイルパスへのSQL Serverサービスアカウントのアクセス権が必要

## 備考

- Name未指定時は「random-{乱数}」の名前で作成
- セカンダリファイルグループは複数ファイルをサポートし、I/O分散に有効
- デフォルトファイルグループをSecondaryに設定すると、新規オブジェクトはセカンダリに作成される

---

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

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

### 推奨読解順序

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

多数のパラメータ定義を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDatabase.ps1 | `public/New-DbaDatabase.ps1` | 178-208行目のparamブロック |

**読解のコツ**: ファイルサイズ関連パラメータはすべてint32（MB単位）。LogFileSuffixのデフォルトは'_log'。

#### Step 2: 詳細設定判定を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDatabase.ps1 | `public/New-DbaDatabase.ps1` | 210-216行目のbeginブロック |

**主要処理フロー**:
- **212行目**: Test-Boundで詳細設定パラメータの検出

#### Step 3: ファイルグループ・ファイル作成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDatabase.ps1 | `public/New-DbaDatabase.ps1` | 297-450行目の詳細設定処理 |

**主要処理フロー**:
- **299-304行目**: PRIMARYファイルグループ作成
- **306-348行目**: プライマリデータファイル作成（modelサイズ比較含む）
- **350-389行目**: トランザクションログ作成
- **391-450行目**: セカンダリファイルグループ・ファイル作成

#### Step 4: データベース作成と後処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaDatabase.ps1 | `public/New-DbaDatabase.ps1` | 453-482行目のDB作成と後処理 |

**主要処理フロー**:
- **456行目**: $newdb.Create()
- **461-468行目**: SetOwner()
- **471-477行目**: SetDefaultFileGroup()
- **481行目**: Get-DbaDatabase

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

```
New-DbaDatabase
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続
    │
    ├─ Get-DbaAvailableCollation
    │      └─ 照合順序検証
    │
    ├─ Get-DbaDefaultPath
    │      └─ デフォルトパス取得
    │
    ├─ New-DbaDirectory
    │      └─ ディレクトリ作成
    │
    ├─ New-Object Database
    │      └─ SMO Databaseオブジェクト作成
    │
    ├─ New-Object Filegroup
    │      └─ ファイルグループ作成
    │
    ├─ New-Object DataFile
    │      └─ データファイル作成
    │
    ├─ New-Object LogFile
    │      └─ ログファイル作成
    │
    ├─ $newdb.Create()
    │      └─ データベース作成実行
    │
    └─ Get-DbaDatabase
           └─ 作成されたDB取得
```

### データフロー図

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

SqlInstance ─────────▶ Connect-DbaInstance
Name ─────────────────▶ (ランダム生成)
                              │
                              ▼
DataFilePath ─────────▶ ディレクトリ確認/作成
LogFilePath ──────────▶
                              │
                              ▼
Collation ────────────▶ SMO Database作成
RecoveryModel ────────▶
                              │
                              ▼
PrimaryFilesize ──────▶ ファイルグループ設定
SecondaryFileCount ───▶ ファイル設定
*Growth, *MaxSize ────▶
                              │
                              ▼
                       Database.Create()
                              │
                              ▼
Owner ─────────────────▶ SetOwner()
DefaultFileGroup ──────▶ SetDefaultFileGroup()
                              │
                              ▼
                       Get-DbaDatabase ────────────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDatabase.ps1 | `public/New-DbaDatabase.ps1` | ソース | メイン機能の実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベース取得 |
| Get-DbaDefaultPath.ps1 | `public/Get-DbaDefaultPath.ps1` | ソース | デフォルトパス取得 |
| Get-DbaAvailableCollation.ps1 | `public/Get-DbaAvailableCollation.ps1` | ソース | 照合順序取得 |
| New-DbaDirectory.ps1 | `public/New-DbaDirectory.ps1` | ソース | ディレクトリ作成 |
