# バッチ設計書 10-gh-s3actions.ps1

## 概要

本ドキュメントは、GitHub Actions用のS3バックアップ統合テストスクリプト「gh-s3actions.ps1」の設計仕様を記載したものである。

### 本バッチの処理概要

本スクリプトは、GitHub ActionsのCI/CDパイプラインでSQL Server 2022のS3互換ストレージへのバックアップ・リストア機能をテストするPesterテストスクリプトである。MinIOを使用したS3互換テスト環境で、Backup-DbaDatabase、Get-DbaBackupInformation、Restore-DbaDatabase等のコマンドがS3プロトコルで正常に動作することを検証する。

**業務上の目的・背景**：SQL Server 2022から導入されたS3互換オブジェクトストレージへのバックアップ機能は、クラウドストレージやオンプレミスのS3互換ストレージ（MinIO等）への直接バックアップを可能にする重要な機能である。dbatoolsモジュールはこの機能をサポートする必要があり、本スクリプトは Backup-DbaDatabase -StorageBaseUrl パラメータ、Restore-DbaDatabase、Get-DbaBackupInformation等がS3プロトコルで正常に動作することを検証する。また、S3 URLを使用した場合のディレクトリ列挙制限（T-SQLのxp_dirtree/sys.dm_os_enumerate_filesystemはS3非対応）についても検証する。

**バッチの実行タイミング**：GitHub Actionsワークフローにより、プルリクエスト時やmainブランチへのプッシュ時に自動実行される。

**主要な処理内容**：
1. S3認証情報の作成（New-DbaCredential）
2. Backup-DbaDatabase によるS3へのフルバックアップ
3. Backup-DbaDatabase によるS3への差分・ログバックアップ
4. Get-DbaBackupInformation によるS3バックアップ情報取得
5. Restore-DbaDatabase によるS3からのリストア
6. S3フォルダパスの列挙制限テスト
7. ローカルファイルシステムとの対比テスト

**前後の処理との関連**：GitHub Actionsワークフローにより、Docker上のSQL Server 2022インスタンスとMinIO（S3互換ストレージ）が事前に起動される。

**影響範囲**：CI/CDパイプラインのS3バックアップ機能品質保証に影響する。テスト失敗時はプルリクエストのマージがブロックされる。

## バッチ種別

CI/CD / 統合テスト（S3機能特化）

## 実行スケジュール

| 項目 | 内容 |
|-----|------|
| 実行頻度 | イベント駆動（PR/プッシュ時） |
| 実行時刻 | 該当なし |
| 実行曜日 | 該当なし |
| 実行日 | 該当なし |
| トリガー | GitHub Actions（pull_request, push） |

## 実行条件

### 前提条件

| 条件 | 説明 |
|-----|------|
| GitHub Actions環境 | Linux runnerで実行 |
| Docker | SQL Server 2022コンテナとMinIOコンテナが起動済み |
| SQL Server 2022以上 | S3バックアップ機能はSQL Server 2022で追加 |
| 環境変数 | S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY, S3_SECRET_KEY |

### 実行可否判定

GitHub Actionsワークフローの条件に従う。テスト対象のタグ（IntegrationTests, S3）で制御可能。

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | デフォルト値 | 説明 |
|-------------|-----|-----|-------------|------|
| なし | - | - | - | 環境変数からパラメータを取得 |

### 入力データソース

| データソース | 形式 | 説明 |
|-------------|------|------|
| 環境変数 S3_ENDPOINT | 文字列 | MinIOエンドポイント（例: minio:9000） |
| 環境変数 S3_BUCKET | 文字列 | S3バケット名 |
| 環境変数 S3_ACCESS_KEY | 文字列 | S3アクセスキー |
| 環境変数 S3_SECRET_KEY | 文字列 | S3シークレットキー |

## 出力仕様

### 出力データ

| 出力先 | 形式 | 説明 |
|-------|------|------|
| Pesterテスト結果 | コンソール出力 | テスト成功/失敗の詳細 |
| S3ストレージ | .bak/.trn | バックアップファイル（テスト後クリーンアップ） |
| GitHub Actions | ステータス | ワークフローの成功/失敗 |

### 出力ファイル仕様

| 項目 | 内容 |
|-----|------|
| バックアップファイル名 | {dbname}_{type}.bak, {dbname}_{type}.trn |
| 出力先 | s3://{endpoint}/{bucket}/{path} |
| 形式 | SQL Server ネイティブバックアップ |

## 処理フロー

### 処理シーケンス

```
1. BeforeAll: テスト環境セットアップ
   ├─ 認証情報の作成（sa/dbatools.IO）
   ├─ S3設定の取得（環境変数から）
   ├─ S3 URL形式の構築
   └─ dbatoolsモジュールのインポート
2. Context "SQL Server 2022 S3 backup prerequisites"
   ├─ SQL Server 2022以上のバージョン確認
   └─ S3認証情報の作成（New-DbaCredential）
3. Context "Backup-DbaDatabase to S3"
   ├─ テストデータベース作成
   ├─ フルバックアップテスト（StorageBaseUrl）
   ├─ フルバックアップテスト（AzureBaseUrl alias）
   ├─ トランザクションログバックアップテスト
   ├─ 差分バックアップテスト
   └─ MaxTransferSize指定バックアップテスト
4. Context "Get-DbaBackupInformation from S3"
   └─ S3 URLからのバックアップ情報取得テスト
5. Context "Restore-DbaDatabase from S3"
   ├─ S3からのデータベースリストアテスト
   └─ AzureCredential alias互換性テスト
6. Context "S3 directory enumeration limitations"
   ├─ S3フォルダパスの列挙制限テスト
   ├─ 警告メッセージ出力テスト
   ├─ 明示的ファイルパス指定テスト
   ├─ ローカルファイルシステム対比テスト
   └─ PowerShellベースS3列挙テスト（オプション）
7. Context "Cleanup"
   └─ S3認証情報の削除
```

### フローチャート

```mermaid
flowchart TD
    A[テスト開始] --> B[BeforeAll: 環境セットアップ]
    B --> C[SQL Server 2022確認]
    C --> D[S3認証情報作成]
    D --> E[S3バックアップテスト群]
    E --> F[S3バックアップ情報取得テスト]
    F --> G[S3リストアテスト群]
    G --> H[S3列挙制限テスト群]
    H --> I[クリーンアップ]
    I --> J[テスト終了]
```

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

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

| 処理 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| テストデータベース作成 | - | CREATE DATABASE | Full Recovery Modelで作成 |
| テストデータ挿入 | TestTable, RestoreTest | CREATE TABLE, INSERT | テストデータ作成 |
| バックアップ | - | BACKUP DATABASE/LOG | S3へのバックアップ |
| リストア | - | RESTORE DATABASE | S3からのリストア |
| 認証情報操作 | sys.credentials | CREATE/DROP CREDENTIAL | S3認証情報管理 |

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

#### TestTable（S3バックアップテスト用）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE TABLE | ID, Name | INT, VARCHAR(100) | テストテーブル |
| INSERT | ID, Name | 1/'Test Row 1', 2/'Test Row 2' | テストデータ |

#### RestoreTest（S3リストアテスト用）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| CREATE TABLE | ID, Value | INT, VARCHAR(50) | テストテーブル |
| INSERT | ID, Value | 100/'S3 Restore Test' | テストデータ |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | バージョンエラー | SQL Server 2022未満 | テスト失敗 |
| - | S3接続エラー | MinIOに接続できない | テスト失敗 |
| - | 認証情報エラー | S3認証情報が無効 | テスト失敗 |
| - | バックアップエラー | S3へのバックアップ失敗 | テスト失敗 |
| - | リストアエラー | S3からのリストア失敗 | テスト失敗 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | なし |
| リトライ間隔 | 該当なし |
| リトライ対象エラー | 該当なし |

### 障害時対応

テスト失敗時はGitHub Actionsワークフローが失敗ステータスになる。各Contextの AfterAll でテストデータベースとS3認証情報のクリーンアップが行われる。

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

| 項目 | 内容 |
|-----|------|
| トランザクション範囲 | バックアップ/リストア単位 |
| コミットタイミング | 各操作完了時 |
| ロールバック条件 | テスト失敗時も明示的なロールバックなし（クリーンアップで削除） |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定処理件数 | 約15テストケース |
| 目標処理時間 | 10分以内 |
| メモリ使用量上限 | GitHub Actions runner制限内 |

## 排他制御

GitHub Actionsにより同一PRへの同時実行は制限される。テスト用データベース名はプレフィックス「dbatoolsci_s3」で区別される。

## ログ出力

| ログ種別 | 出力タイミング | 出力内容 |
|---------|--------------|---------|
| Pester出力 | テスト実行時 | テスト名、結果、所要時間 |
| Write-Host | デバッグ時 | SQL Serverバージョン情報 |
| Warning | S3列挙エラー時 | S3 paths cannot be enumerated using T-SQL |

## 監視・アラート

| 監視項目 | 閾値 | アラート先 |
|---------|-----|----------|
| テスト失敗 | 1件以上 | GitHub PR/コミットステータス |

## 備考

- 本スクリプトは.github/scripts/配下に配置されている
- SQL Server 2022以上が必要（S3バックアップ機能）
- MinIOを使用したS3互換テスト環境
- S3認証情報形式: IDENTITY='S3 Access Key', SECRET='{AccessKey}:{SecretKey}'
- AzureBaseUrl/AzureCredentialパラメータは後方互換性のためのエイリアス
- S3フォルダパスのT-SQL列挙は不可（xp_dirtree/sys.dm_os_enumerate_filesystemはS3非対応）

### テスト一覧

| テスト名 | 対象機能 | 備考 |
|---------|---------|------|
| SQL Server 2022以上確認 | バージョンチェック | 前提条件 |
| S3認証情報作成 | New-DbaCredential | 前提条件 |
| S3フルバックアップ（StorageBaseUrl） | Backup-DbaDatabase | 新パラメータ |
| S3フルバックアップ（AzureBaseUrl） | Backup-DbaDatabase | 後方互換性 |
| S3ログバックアップ | Backup-DbaDatabase -Type Log | トランザクションログ |
| S3差分バックアップ | Backup-DbaDatabase -Type Differential | 差分 |
| S3バックアップ（MaxTransferSize） | Backup-DbaDatabase | パフォーマンスオプション |
| S3バックアップ情報取得 | Get-DbaBackupInformation | メタデータ取得 |
| S3からリストア | Restore-DbaDatabase | データ復元 |
| S3リストア（AzureCredential） | Restore-DbaDatabase | 後方互換性 |
| S3フォルダ列挙制限 | Get-DbaBackupInformation | 警告確認 |
| ローカル列挙対比 | Restore-DbaDatabase | 対比テスト |
| PowerShell S3列挙 | AWS.Tools.S3 | オプション |
| S3認証情報削除 | Remove-DbaCredential | クリーンアップ |

### S3 URL形式

```
s3://{endpoint}/{bucket}/{path}
例: s3://minio:9000/dbatools/backup.bak
```

### S3認証情報の形式

```sql
CREATE CREDENTIAL [S3BackupCredential]
WITH IDENTITY = 'S3 Access Key',
SECRET = '{AccessKeyID}:{SecretKeyID}'
```
