# 機能設計書 621-New-DbaDbSequence

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`New-DbaDbSequence`コマンドレットに関する機能設計書である。このコマンドレットは、SQL Serverデータベースに新しいシーケンスオブジェクトを作成する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Server 2012以降で利用可能なシーケンスオブジェクトは、IDENTITY列の代替として連番生成に使用される。シーケンスは複数テーブル間での連番共有、より柔軟な番号制御、値のリセットや変更が可能という利点がある。この機能により、DBAはPowerShellから効率的にシーケンスを作成・管理できる。

**機能の利用シーン**：
- 新規アプリケーションのデプロイ時にシーケンスを一括作成する場合
- 既存のIDENTITY列をシーケンスに移行する場合
- 複数テーブルで共有する連番が必要な場合
- テスト環境でのシーケンス設定を本番環境に適用する場合

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. 指定されたデータベースの取得
3. SQL Server 2012以上のバージョンチェック
4. シーケンスの重複チェック
5. スキーマの存在確認と必要に応じた自動作成
6. シーケンスオブジェクトの生成と各プロパティ設定
7. データ型（システム型/ユーザー定義型）の解決
8. シーケンスの作成実行と結果出力

**関連システム・外部連携**：SQL Server Management Objects (SMO)を使用してSQL Serverと連携する。

**権限による制御**：シーケンス作成にはデータベース内でのCREATE SEQUENCE権限が必要。スキーマを新規作成する場合は追加のDDL権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLIコマンド | 主画面 | PowerShellコンソールからの実行 |

## 機能種別

CRUD操作（Create）/ DDL実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | string[] | 条件付き | 対象データベース名（SqlInstance指定時は必須） | SqlInstance指定時に必須 |
| Sequence | string[] | Yes | 作成するシーケンス名 | 一意名（スキーマ内で重複不可） |
| Schema | string | No | シーケンスを作成するスキーマ（デフォルト: dbo） | - |
| IntegerType | string | No | データ型（デフォルト: bigint） | tinyint, smallint, int, bigint, またはユーザー定義型 |
| StartWith | long | No | 開始値（デフォルト: 1） | - |
| IncrementBy | long | No | 増分値（デフォルト: 1） | - |
| MinValue | long | No | 最小値 | - |
| MaxValue | long | No | 最大値 | - |
| Cycle | switch | No | 循環を有効にするか | - |
| CacheSize | int32 | No | キャッシュサイズ（0=NO CACHE） | 0以上の整数 |
| InputObject | Database[] | No | パイプライン入力用データベースオブジェクト | - |
| EnableException | switch | No | 例外処理モード切替 | - |

### 入力データソース

- PowerShellコマンドラインからのパラメータ入力
- パイプラインからのGet-DbaDatabase出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホスト名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| Database | string | データベース名 |
| Schema | string | スキーマ名 |
| Name | string | シーケンス名 |
| DataType | string | データ型 |
| StartValue | long | 開始値 |
| IncrementValue | long | 増分値 |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance指定時にDatabaseが必須かチェック
2. データベースオブジェクト取得
   └─ Get-DbaDatabase経由でInputObjectに追加
3. データベースごとのループ処理
   └─ 3.1 SQL Server 2012以上のバージョンチェック
   └─ 3.2 シーケンス重複チェック
   └─ 3.3 ShouldProcess確認
   └─ 3.4 スキーマの存在確認・作成
   └─ 3.5 シーケンスオブジェクト生成
   └─ 3.6 プロパティ設定（StartWith, IncrementBy, Cycle等）
   └─ 3.7 データ型解決（ユーザー定義型対応）
   └─ 3.8 キャッシュ設定
   └─ 3.9 シーケンス作成実行（Create()メソッド）
   └─ 3.10 作成したシーケンスを取得して出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance && !Database?}
    B -->|Yes| C[エラー: Database必須]
    B -->|No| D[データベースオブジェクト取得]
    D --> E[foreach db in InputObject]
    E --> F{Version >= 11?}
    F -->|No| G[警告: SQL 2012以上が必要]
    G --> E
    F -->|Yes| H{シーケンス存在?}
    H -->|Yes| I[警告: 既存シーケンス]
    I --> E
    H -->|No| J[ShouldProcess確認]
    J --> K[スキーマ確認/作成]
    K --> L[Sequenceオブジェクト作成]
    L --> M[プロパティ設定]
    M --> N[データ型解決]
    N --> O[キャッシュ設定]
    O --> P[Create実行]
    P --> Q[結果出力]
    Q --> E
    E --> R[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | バージョン制約 | SQL Server 2012以上が必要 | 常時 |
| BR-002 | 重複禁止 | 同一スキーマ内で同名シーケンスは作成不可 | 常時 |
| BR-003 | スキーマ自動作成 | 指定スキーマが存在しない場合は自動作成 | Schema指定時 |
| BR-004 | キャッシュ設定 | CacheSize=0でNO CACHE、未指定でDefaultCache | CacheSize指定時 |

### 計算ロジック

- データ型解決: IntegerTypeがユーザー定義型の場合、"schema.typename"形式をパースして該当する型を検索

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| シーケンス作成 | sys.sequences | INSERT | 新規シーケンスメタデータ登録 |
| スキーマ作成 | sys.schemas | INSERT | スキーマが存在しない場合に作成 |

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

#### sys.sequences

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | name | Sequenceパラメータ値 | シーケンス名 |
| INSERT | start_value | StartWithパラメータ値 | 開始値 |
| INSERT | increment | IncrementByパラメータ値 | 増分値 |
| INSERT | is_cycling | Cycleパラメータ値 | 循環フラグ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | SqlInstance指定時にDatabase未指定 | Databaseパラメータを指定する |
| - | Stop-Function | SQL Server 2012未満 | SQL Server 2012以上にアップグレード |
| - | Stop-Function | シーケンス名重複 | 別の名前を使用 |
| - | Stop-Function | 作成失敗 | エラーメッセージを確認し権限等を見直す |

### リトライ仕様

リトライ機能なし（失敗時はStop-Functionで処理継続またはエラー出力）

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

SMOのCreate()メソッドによる暗黙的トランザクション。失敗時は自動ロールバック。

## パフォーマンス要件

特に定義なし。通常のDDL操作として即時完了が期待される。

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

- CREATE SEQUENCE権限が必要
- SqlCredentialによる認証情報の安全な受け渡し
- スキーマ作成時は追加のDDL権限が必要

## 備考

- SQL Server 2012（バージョン11）以上が必須
- パイプラインからGet-DbaDatabase出力を受け取り可能
- WhatIfおよびConfirmをサポート

---

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

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

### 推奨読解順序

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

SMOのSequenceオブジェクト構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Microsoft.SqlServer.Management.Smo.Sequence | SMO Assembly | シーケンスの各プロパティ（StartValue, IncrementValue, IsCycleEnabled等） |

**読解のコツ**: SMO Sequenceオブジェクトには、StartValue、IncrementValue、MinValue、MaxValue、IsCycleEnabled、CacheSize、SequenceCacheType等の主要プロパティがある。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaDbSequence.ps1 | `public/New-DbaDbSequence.ps1` | パラメータ定義と処理フローの全体像 |

**主要処理フロー**:
1. **131-149行目**: パラメータ定義（SqlInstance, Database, Sequence等）
2. **150-159行目**: processブロック開始、パラメータ検証とデータベース取得
3. **161-227行目**: メインループ（データベースごとのシーケンス作成処理）

#### Step 3: 各処理層を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaDbSequence.ps1 | `public/New-DbaDbSequence.ps1` | シーケンス作成ロジックの詳細 |

**主要処理フロー**:
- **163-165行目**: SQL Serverバージョンチェック（Version.Major >= 11）
- **167-169行目**: シーケンス重複チェック
- **173-179行目**: スキーマの存在確認と自動作成
- **182-199行目**: シーケンスオブジェクト生成とプロパティ設定
- **188-199行目**: データ型解決（ユーザー定義型対応含む）
- **201-218行目**: MinValue、MaxValue、CacheSize設定
- **220-221行目**: シーケンス作成実行とGet-DbaDbSequenceによる結果取得

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

```
New-DbaDbSequence
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Get-DbaDatabase (データベースオブジェクト取得)
    │
    ├─ Get-DbaDbSchema (スキーマ確認)
    │      └─ スキーマ存在チェック
    │
    ├─ New-DbaDbSchema (スキーマ自動作成)
    │      └─ 存在しない場合のみ実行
    │
    ├─ [SMO] New-Object Sequence (シーケンスオブジェクト生成)
    │      └─ プロパティ設定
    │      └─ Create() メソッド実行
    │
    └─ Get-DbaDbSequence (作成結果取得)
```

### データフロー図

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

SqlInstance/Database ───▶ Get-DbaDatabase ───────────────▶ Database[]
                                 │
                                 ▼
Sequence/Schema/Props ───▶ New-Object Sequence ──────────▶ Sequence object
                                 │
                                 ▼
                          Sequence.Create() ─────────────▶ DB登録
                                 │
                                 ▼
                          Get-DbaDbSequence ─────────────▶ Sequence結果
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaDbSequence.ps1 | `public/New-DbaDbSequence.ps1` | ソース | メインコマンドレット |
| Get-DbaDbSequence.ps1 | `public/Get-DbaDbSequence.ps1` | ソース | シーケンス取得（作成後の確認用） |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
| Get-DbaDbSchema.ps1 | `public/Get-DbaDbSchema.ps1` | ソース | スキーマ存在確認 |
| New-DbaDbSchema.ps1 | `public/New-DbaDbSchema.ps1` | ソース | スキーマ自動作成 |
