# 機能設計書 659-Enable-DbaStartupProcedure

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Enable-DbaStartupProcedure` 関数の機能設計を記述するものである。本機能はmasterデータベースのストアドプロシージャをSQL Serverサービス起動時に自動実行するように設定するコマンドレットである。

### 本機能の処理概要

**業務上の目的・背景**：
SQL Serverの起動時に特定のストアドプロシージャを自動実行することで、サービス再起動後も初期化スクリプトの手動実行が不要になる。DBAが重要なメンテナンスプロシージャ、監視セットアップ、カスタム構成を確実にインスタンス起動時に適用するために使用する。本機能はSMOを通じてプロシージャのStartupプロパティを変更し、sp_procoption @OptionValue = 'on' と同等の操作を提供する。

**機能の利用シーン**：
- サーバー初期化スクリプトの自動実行設定
- 監視エージェントのセットアッププロシージャ登録
- カスタム構成プロシージャのスタートアップ登録
- DR環境構築時の自動実行設定

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. 対象プロシージャの特定（パラメータ指定）
3. SMO StoredProcedure オブジェクトの Startup プロパティを true に設定
4. Alter() メソッドによる変更の適用
5. 結果オブジェクトの出力

**関連システム・外部連携**：
- SQL Server SMO (StoredProcedure オブジェクト)
- Get-ObjectNameParts ヘルパー関数によるプロシージャ名解析

**権限による制御**：
- masterデータベースへの変更権限が必要
- プロシージャのスタートアップ設定変更には sysadmin 権限が推奨

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI (PowerShell) | 主画面 | コマンドライン実行によるスタートアップ有効化 |

## 機能種別

設定変更処理（UPDATE）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | 必須、パイプライン入力可 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| StartupProcedure | object[] | No | 対象プロシージャ名（スキーマ修飾可） | - |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

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

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名（常に'master'） |
| Schema | string | プロシージャのスキーマ名 |
| Name | string | プロシージャ名 |
| Startup | bool | スタートアップ状態（成功時は常にtrue） |
| Action | string | 実行アクション（常に'Enable'） |
| Status | bool | 操作成否（true=成功、false=スキップ/失敗） |
| Note | string | 結果メッセージ |

### 出力先

PowerShellパイプライン（SMO StoredProcedure オブジェクトに拡張プロパティを追加）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（beginブロック）
   └─ $action = 'Enable', $startup = $true 設定

2. メイン処理（processブロック）
   └─ 各SQL Serverインスタンスに対して処理
       └─ SQL Serverへの接続
       └─ masterデータベース取得
       └─ 各StartupProcedureの処理
           └─ Get-ObjectNameParts でプロシージャ名解析
           └─ StoredProcedures.Item でオブジェクト取得
           └─ 現在のStartup状態チェック
           └─ 既にtrueなら"already performed"
           └─ ShouldProcess確認
           └─ Startup = true, Alter()実行
           └─ 結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[各SqlInstanceをループ]
    B --> C[SQL Server接続]
    C --> D{接続成功?}
    D -->|No| E[エラー: Continue]
    D -->|Yes| F[masterデータベース取得]
    F --> G[各StartupProcedureをループ]
    G --> H[Get-ObjectNameParts]
    H --> I{解析成功?}
    I -->|No| J[エラー: Continue]
    I -->|Yes| K[StoredProcedures.Item]
    K --> L{存在する?}
    L -->|No| M[エラー: Continue]
    L -->|Yes| N{Startup既にtrue?}
    N -->|Yes| O[Status=false, Note="already performed"]
    N -->|No| P{ShouldProcess?}
    P -->|No| Q[Status=false, Note="skipped"]
    P -->|Yes| R[Startup=true, Alter実行]
    R --> S{成功?}
    S -->|Yes| T[Status=true, Note="succeded"]
    S -->|No| U[Status=false, Note="failed"]
    O --> V[拡張プロパティ追加]
    Q --> V
    T --> V
    U --> V
    V --> W[Select-DefaultView出力]
    W --> X{次のプロシージャ?}
    X -->|Yes| G
    X -->|No| Y{次のインスタンス?}
    Y -->|Yes| B
    Y -->|No| Z[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | 既存状態チェック | 既にStartup=trueなら操作不要 | 処理前チェック時 |
| BR-002 | masterデータベース限定 | スタートアッププロシージャはmasterデータベースのみ | 常時 |
| BR-003 | スキーマ修飾名対応 | '[dbo].[ProcName]'形式を解析 | プロシージャ名解析時 |
| BR-004 | 高影響確認 | ConfirmImpact = 'High' | ShouldProcess時 |

### 計算ロジック

特になし（単純なブール値の設定）

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| プロシージャ取得 | master.sys.procedures | SELECT | StoredProcedures.Item() |
| スタートアップ設定変更 | - | UPDATE（間接） | SMO Alter() |

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

#### sys.procedures（間接）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | is_auto_executed | 1（true） | SMO Startup プロパティ経由 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Serverへの接続失敗 | Stop-Function with -Continue |
| - | 解析エラー | プロシージャ名の解析失敗 | Stop-Function with -Continue |
| - | 存在エラー | プロシージャが存在しない | Stop-Function with -Continue |
| - | 実行エラー | Alter()失敗 | Status=false, Note="failed" |

### リトライ仕様

自動リトライは実装されていない。

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

- SMO Alter() によるメタデータ変更
- 個別操作ごとに即座にコミット

## パフォーマンス要件

- 単一プロシージャの操作は即座に完了
- 複数インスタンス/プロシージャをループ処理可能

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

- sysadmin権限が推奨
- ShouldProcess によるConfirm/WhatIf対応
- ConfirmImpact='High' で確認プロンプト表示

## 備考

- Disable-DbaStartupProcedure と対になる機能
- SMO Startup プロパティを使用（sp_procoption のラッパー）
- Disable-DbaStartupProcedureと異なり、InputObject パイプライン入力なし

---

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

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

### 推奨読解順序

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

入出力で使用されるデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Enable-DbaStartupProcedure.ps1 | `public/Enable-DbaStartupProcedure.ps1` | 148-157行目: Add-Member によるプロパティ追加 |

**読解のコツ**: SMO StoredProcedure オブジェクトにNotePropertyを追加して出力形式を拡張している。Disable-DbaStartupProcedureと同じ出力形式。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Enable-DbaStartupProcedure.ps1 | `public/Enable-DbaStartupProcedure.ps1` | 87-94行目: パラメータ定義 |
| 2-2 | Enable-DbaStartupProcedure.ps1 | `public/Enable-DbaStartupProcedure.ps1` | 95-98行目: beginブロック |

**主要処理フロー**:
1. **96行目**: $action = 'Enable'
2. **97行目**: $startup = $true

#### Step 3: メイン処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Enable-DbaStartupProcedure.ps1 | `public/Enable-DbaStartupProcedure.ps1` | 100-160行目: processブロック |

**主要処理フロー**:
- **101-106行目**: Connect-DbaInstance
- **109行目**: masterデータベース取得
- **113行目**: Get-ObjectNameParts でプロシージャ名解析
- **116行目**: StoredProcedures.Item でSMOオブジェクト取得

#### Step 4: スタートアップ有効化処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Enable-DbaStartupProcedure.ps1 | `public/Enable-DbaStartupProcedure.ps1` | 121-142行目: 有効化処理 |

**主要処理フロー**:
- **122-125行目**: 既にtrueなら"already performed"
- **127-135行目**: ShouldProcess確認とAlter()実行
- **128-129行目**: `$sp.Startup = $startup`, `$sp.Alter()`

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

```
Enable-DbaStartupProcedure
    │
    ├─ begin ブロック
    │      └─ $action, $startup 初期化
    │
    └─ process ブロック
           └─ 各SqlInstanceをループ
                  │
                  ├─ Connect-DbaInstance
                  │
                  ├─ $server.Databases['master']
                  │
                  └─ 各StartupProcedureをループ
                         │
                         ├─ Get-ObjectNameParts
                         │
                         ├─ StoredProcedures.Item
                         │
                         ├─ Startup状態チェック
                         │
                         ├─ ShouldProcess
                         │      └─ $sp.Startup = $true
                         │      └─ $sp.Alter()
                         │
                         ├─ Add-Member（プロパティ追加）
                         │
                         └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ────┐
                ├──▶ Connect-DbaInstance
SqlCredential ──┤            │
                │            ▼
                │    $server.Databases['master']
                │            │
StartupProc ────┘            ▼
                     各StartupProcedureをループ
                             │
                             ▼
                     Get-ObjectNameParts
                             │
                             ▼
                     StoredProcedures.Item
                             │
                             ▼
                     ┌───────┴───────┐
                     │ Startup状態   │
                     └───────┬───────┘
                     false│       │true
                          ▼       │
                     ShouldProcess │
                          │       │
                          ▼       ▼
                     Startup=true "already performed"
                     Alter()
                          │
                          ▼
                     Add-Member
                     (ComputerName, InstanceName,
                      SqlInstance, Database,
                      Action, Status, Note)
                          │
                          ▼
                     ─────────────────────────▶ StoredProcedure
                                                (拡張プロパティ付き)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Enable-DbaStartupProcedure.ps1 | `public/Enable-DbaStartupProcedure.ps1` | ソース | メイン機能実装 |
| Disable-DbaStartupProcedure.ps1 | `public/Disable-DbaStartupProcedure.ps1` | ソース | 対になる無効化機能 |
| Get-DbaStartupProcedure.ps1 | `public/Get-DbaStartupProcedure.ps1` | ソース | スタートアッププロシージャ取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
