# 機能設計書 624-Set-DbaDbSequence

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Set-DbaDbSequence`コマンドレットに関する機能設計書である。このコマンドレットは、既存のSQL Serverシーケンスオブジェクトのプロパティを変更する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：デプロイ後のシーケンス設定変更、増分値の調整、シーケンスのリスタート、最小値・最大値の変更、サイクル動作の切り替え、キャッシュ設定の最適化などが必要になる場面は多い。この機能により、DBAはシーケンスを再作成することなく、既存のシーケンス設定を柔軟に変更できる。

**機能の利用シーン**：
- シーケンス値のリスタート（データ移行後のギャップ修正など）
- 増分値の変更
- 最小値・最大値の調整
- サイクル動作の有効化・無効化
- パフォーマンスチューニングのためのキャッシュサイズ変更

**主要な処理内容**：
1. 対象SQL Serverインスタンスへの接続確立
2. 指定されたデータベースとシーケンスの取得
3. IncrementByが0でないことの検証
4. シーケンスオブジェクトのプロパティ更新
5. Alter()メソッドによる変更の永続化
6. 更新後のシーケンスオブジェクト出力

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

**権限による制御**：シーケンスに対するALTER権限が必要。

## 関連画面

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

## 機能種別

CRUD操作（Update）/ DDL実行

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | No | 対象SQL Serverインスタンス | 有効なインスタンス名 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | string[] | 条件付き | 対象データベース名（SqlInstance指定時は必須） | SqlInstance指定時に必須 |
| Sequence | string[] | Yes | 変更対象シーケンス名 | - |
| Schema | string | No | シーケンスのスキーマ（デフォルト: dbo） | - |
| RestartWith | long | No | シーケンスをリスタートする値 | - |
| IncrementBy | long | No | 新しい増分値 | 0は不可 |
| 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出力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| Name | string | シーケンス名 |
| Schema | string | スキーマ名 |
| Owner | string | 所有者 |
| StartValue | long | 開始値 |
| CurrentValue | long | 現在値 |
| IncrementValue | long | 増分値 |
| MinValue | long | 最小値 |
| MaxValue | long | 最大値 |
| IsCycleEnabled | bool | サイクル有効フラグ |
| SequenceCacheType | enum | キャッシュタイプ |
| CacheSize | int | キャッシュサイズ |

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. パラメータ検証
   └─ 1.1 SqlInstance指定時にDatabaseが必須かチェック
   └─ 1.2 IncrementByが0でないかチェック
2. データベースオブジェクト取得
   └─ Get-DbaDatabase経由でInputObjectに追加
3. データベースごとのループ処理
   └─ 3.1 ShouldProcess確認
   └─ 3.2 Get-DbaDbSequenceでシーケンス取得
   └─ 3.3 シーケンス存在チェック
   └─ 3.4 プロパティ更新（IncrementBy, Cycle, RestartWith等）
   └─ 3.5 キャッシュ設定更新
   └─ 3.6 Alter()メソッド実行
   └─ 3.7 データベースリフレッシュと結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{SqlInstance && !Database?}
    B -->|Yes| C[エラー: Database必須]
    B -->|No| D{IncrementBy == 0?}
    D -->|Yes| E[エラー: IncrementByは0不可]
    D -->|No| F[データベースオブジェクト取得]
    F --> G[foreach db in InputObject]
    G --> H[ShouldProcess確認]
    H --> I[Get-DbaDbSequence]
    I --> J{シーケンス存在?}
    J -->|No| K[警告: シーケンス未発見]
    K --> G
    J -->|Yes| L[プロパティ更新]
    L --> M[キャッシュ設定]
    M --> N[Alter実行]
    N --> O[Refresh & 出力]
    O --> G
    G --> P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | IncrementBy制約 | IncrementByに0は指定不可 | IncrementBy指定時 |
| BR-002 | RestartWithの動作 | SMOはStartValueを変更することでリスタートを実行 | RestartWith指定時 |
| BR-003 | Cycle設定 | スイッチの指定有無でIsCycleEnabledを設定 | 常時 |
| BR-004 | キャッシュ設定 | CacheSize=0でNO CACHE、未指定でDefaultCache | CacheSize指定時 |
| BR-005 | 高影響確認 | ConfirmImpact='High'のためデフォルトで確認プロンプト | 常時 |

### 計算ロジック

- RestartWithパラメータはSMOのStartValueプロパティに設定される。Alter()実行時にCurrentValueも更新される。

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| シーケンス更新 | sys.sequences | UPDATE | シーケンスメタデータ更新 |

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

#### sys.sequences

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | start_value | RestartWithパラメータ値 | リスタート時 |
| UPDATE | increment | IncrementByパラメータ値 | 増分変更時 |
| UPDATE | minimum_value | MinValueパラメータ値 | 最小値変更時 |
| UPDATE | maximum_value | MaxValueパラメータ値 | 最大値変更時 |
| UPDATE | is_cycling | Cycleパラメータ値 | サイクル設定変更時 |
| UPDATE | is_cached / cache_size | CacheSizeパラメータ値 | キャッシュ設定変更時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | Stop-Function | SqlInstance指定時にDatabase未指定 | Databaseパラメータを指定 |
| - | Stop-Function | IncrementByが0 | 0以外の値を指定 |
| - | Stop-Function | シーケンスが見つからない | シーケンス名とスキーマを確認 |
| - | Stop-Function | Alter()実行失敗 | 権限確認、値の妥当性確認 |

### リトライ仕様

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

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

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

## パフォーマンス要件

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

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

- ALTER権限が必要
- SqlCredentialによる認証情報の安全な受け渡し
- ConfirmImpact='High'による誤変更防止

## 備考

- パイプラインからGet-DbaDatabase出力を受け取り可能
- WhatIfおよびConfirmをサポート
- 変更後にデータベースをRefresh()して最新状態を取得

---

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

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

### 推奨読解順序

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

SMO Sequenceオブジェクトの変更可能プロパティを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Set-DbaDbSequence.ps1 | `public/Set-DbaDbSequence.ps1` | .OUTPUTS セクション - 出力プロパティ一覧 |

**読解のコツ**: 変更可能なプロパティは、IncrementValue, StartValue（リスタート用）, MinValue, MaxValue, IsCycleEnabled, SequenceCacheType, CacheSize。

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

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

**主要処理フロー**:
1. **117-135行目**: パラメータ定義（ConfirmImpact='High'）
2. **136-199行目**: processブロック全体
3. **138-146行目**: パラメータ検証（Database必須、IncrementBy != 0）

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Set-DbaDbSequence.ps1 | `public/Set-DbaDbSequence.ps1` | プロパティ更新ロジック |

**主要処理フロー**:
- **156行目**: Get-DbaDbSequenceでシーケンス取得
- **162-164行目**: IncrementBy更新
- **166行目**: IsCycleEnabled設定（Cycleスイッチの状態）
- **168-170行目**: RestartWith処理（StartValueに設定）
- **172-178行目**: MinValue/MaxValue更新
- **180-189行目**: キャッシュ設定（NoCache/CacheWithSize/DefaultCache）
- **191-193行目**: Alter()実行とRefresh()

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

```
Set-DbaDbSequence
    │
    ├─ Test-Bound (パラメータ検証)
    │
    ├─ Get-DbaDatabase (データベースオブジェクト取得)
    │
    ├─ Get-DbaDbSequence (シーケンスオブジェクト取得)
    │
    ├─ [SMO] Sequence.Alter() (変更の永続化)
    │
    └─ [SMO] Database.Refresh() (状態更新)
```

### データフロー図

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

SqlInstance/Database ───▶ Get-DbaDatabase ───────────────▶ Database[]
                                │
Sequence/Schema ────────────────▶
                                │
                                ▼
                          Get-DbaDbSequence ─────────────▶ Sequence object
                                │
RestartWith/IncrementBy ────────▶
MinValue/MaxValue/Cycle ────────▶ プロパティ更新
CacheSize ──────────────────────▶
                                │
                                ▼
                          Alter() 実行 ───────────────────▶ DB更新
                                │
                                ▼
                          Refresh() & 出力 ───────────────▶ Sequence object
```

### 関連ファイル一覧

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