# 機能設計書 534-New-DbaDbSchema

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるNew-DbaDbSchema機能の設計仕様を定義するものである。この機能はSQL Serverデータベースに新しいスキーマを作成し、指定された所有者を設定する。

### 本機能の処理概要

**業務上の目的・背景**：データベーススキーマは、オブジェクトを論理的にグループ化し、セキュリティ境界を実装するための重要な構成要素である。マルチテナントアプリケーション、セキュリティモデル設計、組織的なデータベース開発において、スキーマによるオブジェクト分離が必要となる。本機能は、複数のデータベースに対して一括でスキーマを作成でき、所有者の指定も可能である。

**機能の利用シーン**：
- アプリケーションのデータベース初期セットアップ
- マルチテナント環境でのテナント別スキーマ作成
- 開発・テスト環境のスキーマ構成複製
- セキュリティ境界実装のためのスキーマ分離
- CI/CDパイプラインでのデータベース構成自動化

**主要な処理内容**：
1. Schemaパラメータの必須チェック
2. SqlInstance指定時のDatabaseパラメータ必須チェック
3. Get-DbaDatabase経由でのデータベースオブジェクト取得
4. 既存スキーマ重複チェック
5. SMO Schemaオブジェクト生成と所有者設定
6. Create()メソッドによるスキーマ作成

**関連システム・外部連携**：
- SQL Server Management Objects (SMO) - Schema クラス
- Get-DbaDatabase - データベースオブジェクト取得

**権限による制御**：
- 対象データベースでのCREATE SCHEMA権限
- SchemaOwner指定時は、指定ユーザーがデータベースに存在すること

## 関連画面

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

## 機能種別

データ作成処理（CREATE）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 有効なSQL Server接続文字列 |
| SqlCredential | PSCredential | No | SQL Server接続用の代替認証情報 | 有効なPSCredentialオブジェクト |
| Database | string[] | No* | 対象データベース名（SqlInstance指定時は必須） | - |
| Schema | string[] | Yes* | 作成するスキーマ名（内部で必須チェック） | 既存スキーマと重複不可 |
| SchemaOwner | string | No | スキーマ所有者。省略時はdbo | データベースに存在するユーザー |
| InputObject | Microsoft.SqlServer.Management.Smo.Database[] | No | パイプライン入力のデータベースオブジェクト | - |
| EnableException | switch | No | 例外を呼び出し元にスローする | - |

### 入力データソース

- パラメータ入力（コマンドライン引数）
- パイプライン入力（Get-DbaDatabase出力）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | 作成されたスキーマ名 |
| Owner | string | スキーマ所有者 |
| Parent | Database | 親データベースオブジェクトへの参照 |
| CreateDate | DateTime | 作成日時 |
| State | ObjectState | スキーマオブジェクトの状態 |
| Urn | Urn | Uniform Resource Name |

### 出力先

- 標準出力（Microsoft.SqlServer.Management.Smo.Schema）
- パイプライン出力

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証（processブロック）
   ├─ Schema パラメータ必須チェック
   └─ SqlInstance指定時のDatabase必須チェック

2. データベースオブジェクト取得
   └─ Get-DbaDatabase呼び出しでInputObject構築

3. データベースループ処理
   └─ スキーマループ処理
       ├─ 既存スキーマ重複チェック
       ├─ ShouldProcess確認
       ├─ SMO Schemaオブジェクト生成
       ├─ SchemaOwner設定（指定時）
       ├─ Create()メソッド実行
       └─ 作成済みスキーマオブジェクト出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{Schema指定?}
    B -->|No| C[エラー: Schema必須]
    B -->|Yes| D{SqlInstance指定?}
    D -->|Yes| E{Database指定?}
    E -->|No| F[エラー: Database必須]
    E -->|Yes| G[Get-DbaDatabase]
    D -->|No| H[InputObject使用]
    G --> I[InputObjectに追加]
    H --> I
    I --> J[foreach db in InputObject]
    J --> K[foreach sName in Schema]
    K --> L{スキーマ既存?}
    L -->|Yes| M[エラー: 重複]
    L -->|No| N{ShouldProcess?}
    N -->|No| O[スキップ]
    N -->|Yes| P[New-Object Schema]
    P --> Q{SchemaOwner指定?}
    Q -->|Yes| R[Owner設定]
    Q -->|No| S[Create実行]
    R --> S
    S --> T[スキーマ出力]
    T --> U{次のスキーマ?}
    O --> U
    M --> U
    U -->|Yes| K
    U -->|No| V{次のDB?}
    V -->|Yes| J
    V -->|No| W[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | スキーマ必須 | Schemaパラメータは必須 | 常時 |
| BR-002 | DB必須条件 | SqlInstance指定時はDatabase必須 | SqlInstance指定時 |
| BR-003 | 重複禁止 | 同名スキーマが存在する場合はエラー | 常時 |
| BR-004 | デフォルト所有者 | SchemaOwner省略時はdbo | SchemaOwner未指定時 |

### 計算ロジック

特になし

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| スキーマ作成 | sys.schemas | INSERT | 新規スキーマレコード作成 |

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

#### sys.schemas

SMO Schema.Create()メソッド経由で以下相当のDDLが実行される：
```sql
CREATE SCHEMA [スキーマ名] AUTHORIZATION [所有者]
```

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パラメータ不足 | Schema未指定 | Schemaパラメータを指定 |
| - | パラメータ不足 | SqlInstance指定時にDatabase未指定 | Databaseパラメータを指定 |
| - | 重複エラー | 同名スキーマ既存 | 別のスキーマ名を使用 |
| - | 作成失敗 | 権限不足等 | 必要な権限を付与 |

### リトライ仕様

Stop-Function -Continueにより、エラー発生時も次のスキーマ/データベース処理を継続する。

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

SMO Schema.Create()メソッドが内部的にトランザクションを管理する。

## パフォーマンス要件

- スキーマ作成は通常即座に完了
- 多数のスキーマを一括作成する場合は順次処理

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

- CREATE SCHEMA権限が必要
- SchemaOwner指定時は、指定ユーザーの存在確認が行われる
- 作成されたスキーマは指定所有者に帰属

## 備考

- スキーマ所有者の変更は後からSet-DbaDbSchemaで可能
- 作成されたスキーマにオブジェクトを配置することでセキュリティ境界を実装

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaDbSchema.ps1 | `public/New-DbaDbSchema.ps1` | 出力オブジェクト（SMO Schema）- 137行目で直接出力 |

**読解のコツ**: Create()後にそのまま$newSchemaを出力しているため、SMO Schemaオブジェクトがそのまま返却される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbSchema.ps1 | `public/New-DbaDbSchema.ps1` | param()ブロック（94-103行目）でパラメータ定義確認 |

**主要処理フロー**:
1. **104行目**: processブロック開始
2. **106-109行目**: Schema必須チェック（Test-Bound使用）
3. **111-114行目**: SqlInstance指定時のDatabase必須チェック
4. **116-118行目**: Get-DbaDatabase呼び出し
5. **120-143行目**: データベース/スキーマループと作成処理

#### Step 3: スキーマ作成ロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbSchema.ps1 | `public/New-DbaDbSchema.ps1` | 122-141行目のスキーマ作成処理 |

**主要処理フロー**:
- **124-126行目**: 既存スキーマ重複チェック
- **128行目**: ShouldProcess確認
- **130行目**: New-Object Microsoft.SqlServer.Management.Smo.Schema
- **132-134行目**: SchemaOwner設定（Test-Bound使用）
- **136行目**: Create()メソッド実行
- **137行目**: 作成済みスキーマ出力

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

```
New-DbaDbSchema
    │
    ├─ Test-Bound（パラメータ検証）
    │      ├─ Schema必須チェック
    │      └─ Database必須チェック（SqlInstance指定時）
    │
    ├─ Get-DbaDatabase（データベースオブジェクト取得）
    │      └─ SqlInstance + Database フィルタ
    │
    └─ foreach db
           └─ foreach sName
                  ├─ db.Schemas.Name（重複チェック）
                  ├─ New-Object Schema（SMOオブジェクト生成）
                  ├─ Owner設定（SchemaOwner指定時）
                  └─ Create()メソッド実行
```

### データフロー図

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

SqlInstance ─────────▶ Get-DbaDatabase ───────────▶ Database[]
      +                       │
Database ────────────────────┤
      or                      │
InputObject ─────────────────┤
                              ▼
Schema[] ────────────▶ 重複チェック
                              │
SchemaOwner ─────────────────┤
                              ▼
                       New-Object Schema
                              │
                              ▼
                       Owner設定（オプション）
                              │
                              ▼
                       Create() ──────────────────▶ SMO Schema
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbSchema.ps1 | `public/New-DbaDbSchema.ps1` | ソース | メイン機能実装 |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Test-Bound.ps1 | `private/Test-Bound.ps1` | ソース | パラメータバインドチェック |
