# 機能設計書 623-Select-DbaDbSequenceNextValue

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Select-DbaDbSequenceNextValue`コマンドレットに関する機能設計書である。このコマンドレットは、SQL Serverのシーケンスオブジェクトから次の値を取得してインクリメントする機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：シーケンスオブジェクトの次の値を取得する必要がある場面は多い。テスト目的でのシーケンス動作確認、トラブルシューティング時のシーケンス状態確認、アプリケーションロジックでのシーケンス値取得などが該当する。この機能により、DBAは`SELECT NEXT VALUE FOR`文を直接実行することなく、PowerShellから簡単にシーケンス値を取得できる。

**機能の利用シーン**：
- シーケンスの動作テスト
- シーケンス関連の問題調査
- シーケンス値の手動取得
- スクリプトでのシーケンス値利用

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. 指定されたデータベースの取得
3. `SELECT NEXT VALUE FOR [schema].[sequence]`クエリの実行
4. 次の値を出力（同時にシーケンスカウンターがインクリメントされる）

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

**権限による制御**：シーケンスに対するUPDATE権限が必要（NEXT VALUE FOR実行には更新権限が必要）。

## 関連画面

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

## 機能種別

データ取得 / 副作用あり（シーケンスカウンターインクリメント）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter | No | 対象SQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | string | 条件付き | 対象データベース名（SqlInstance指定時は必須） | SqlInstance指定時に必須 |
| Sequence | string[] | Yes | 値を取得するシーケンス名 | - |
| Schema | string | No | シーケンスのスキーマ（デフォルト: dbo） | - |
| InputObject | Database | No | パイプライン入力用データベースオブジェクト | - |
| EnableException | switch | No | 例外処理モード切替 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| NextValue | System.Int64 | シーケンスの次の値 |

### 出力先

PowerShellパイプライン（64ビット整数値）

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ SqlInstance指定時にDatabaseが必須かチェック
2. データベースオブジェクト取得
   └─ Test-Bound SqlInstanceの場合、Get-DbaDatabase実行
3. SQLクエリ構築
   └─ "SELECT NEXT VALUE FOR [$Schema].[$Sequence] AS NextValue"
4. クエリ実行
   └─ $InputObject.Query()メソッド
5. 結果の.NextValueプロパティを出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance && !Database?}
    B -->|Yes| C[エラー: Database必須]
    B -->|No| D{SqlInstance指定?}
    D -->|Yes| E[Get-DbaDatabase実行]
    E --> F[InputObjectに設定]
    D -->|No| F
    F --> G[SQLクエリ構築]
    G --> H[Query実行]
    H --> I[NextValue出力]
    I --> J[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 破壊的操作 | NEXT VALUE FOR実行はシーケンスカウンターを恒久的にインクリメントする | 常時 |
| BR-002 | デフォルトスキーマ | スキーマ未指定時は'dbo'が使用される | Schema未指定時 |
| BR-003 | 複数シーケンス対応 | Sequenceパラメータは配列で複数指定可能 | - |

### 計算ロジック

- クエリ構築: `"SELECT NEXT VALUE FOR [$($Schema)].[$($Sequence)] AS NextValue"`

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 次の値取得 | sys.sequences | UPDATE | シーケンスの現在値がインクリメントされる |

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

#### sys.sequences

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | current_value | current_value + increment | NEXT VALUE FOR実行による暗黙的更新 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | SqlInstance指定時にDatabase未指定 | Databaseパラメータを指定する |
| - | SQL Error | シーケンスが存在しない | シーケンス名とスキーマを確認 |
| - | SQL Error | 権限不足 | シーケンスへのUPDATE権限を付与 |

### リトライ仕様

リトライ機能なし

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

NEXT VALUE FOR文は自動コミットで実行される。ロールバック不可。

## パフォーマンス要件

特に定義なし。単一のSELECT文として即時実行される。

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

- シーケンスに対するUPDATE権限が必要
- SqlCredentialによる認証情報の安全な受け渡し
- 本番環境での実行は注意（シーケンス値が進む）

## 備考

- 読み取り専用ではない（シーケンスカウンターが変更される）
- SQL Server 2012以上が必要（シーケンス機能自体がSQL 2012で導入）
- WhatIfおよびConfirmをサポート（ただしConfirmImpact='Low'）

---

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

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

### 推奨読解順序

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

出力が単純なInt64値であることを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Select-DbaDbSequenceNextValue.ps1 | `public/Select-DbaDbSequenceNextValue.ps1` | .OUTPUTS セクション - System.Int64 |

**読解のコツ**: 出力は単純な数値であり、オブジェクトではない。クエリ結果の.NextValueプロパティが直接出力される。

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

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

**主要処理フロー**:
1. **80-92行目**: パラメータ定義（ConfirmImpact='Low'）
2. **93-105行目**: processブロック全体
3. **95-98行目**: パラメータ検証（SqlInstance + Database必須チェック）
4. **100-102行目**: データベースオブジェクト取得
5. **104行目**: クエリ実行と結果出力

#### Step 3: コア処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Select-DbaDbSequenceNextValue.ps1 | `public/Select-DbaDbSequenceNextValue.ps1` | クエリ実行部分 |

**主要処理フロー**:
- **104行目**: ワンライナーでクエリ実行と結果取得
  - `$InputObject.Query("SELECT NEXT VALUE FOR [$($Schema)].[$($Sequence)] AS NextValue").NextValue`

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

```
Select-DbaDbSequenceNextValue
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Get-DbaDatabase (SqlInstance指定時)
    │
    └─ Database.Query() (SMO)
           └─ "SELECT NEXT VALUE FOR [schema].[sequence] AS NextValue"
```

### データフロー図

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

SqlInstance/Database ───▶ Get-DbaDatabase ───────────────▶ Database object
                                │
Sequence/Schema ───────────────▶│
                                ▼
                          Query構築・実行
                          "SELECT NEXT VALUE FOR..."
                                │
                                ▼
                          .NextValue取得 ─────────────▶ Int64
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Select-DbaDbSequenceNextValue.ps1 | `public/Select-DbaDbSequenceNextValue.ps1` | ソース | メインコマンドレット |
| Get-DbaDatabase.ps1 | `public/Get-DbaDatabase.ps1` | ソース | データベースオブジェクト取得 |
