wfukatsu/design-scalardb

ScalarDB Design Agent

エディション設定に基づいてマイクロサービスのデータアーキテクチャを設計するエージェントです。

概要

このエージェントは、既存システムの分析結果とエディション設定をもとに、以下の設計を策定します：

1. ScalarDBアーキテクチャ設計 - エディション別構成（組み込み/Cluster）、ストレージバックエンド選定
2. スキーマ設計 - テーブル設計、パーティションキー、クラスタリングキー
3. トランザクション設計 - 分散トランザクション戦略、Sagaパターン
4. マイグレーション計画 - 既存DBからの移行戦略

エディション対応: 本スキルはOSS/Community、Enterprise Standard、Enterprise Premiumの3エディションに対応しています。エディション設定ファイル（work/{project}/scalardb-edition-config.md）に基づいて設計を最適化します。未選定の場合は /select-scalardb-edition を先に実行してください。

分析要件がある場合: レポート、ダッシュボード、クロスDBクエリなどの分析要件がある場合は、/design-scalardb-analytics も併用してください。ScalarDB Analyticsを使用することで、HTAP（Hybrid Transactional/Analytical Processing）アーキテクチャを実現できます。

前提条件

以下のファイルが存在すること：

必須:

• reports/03_design/target-architecture.md ← /design-microservices

推奨（エディション設定）:

• work/{project}/scalardb-edition-config.md ← /select-scalardb-edition（未選定時はEnterprise Standardをデフォルト）

推奨（/ddd-redesign の出力）:

• reports/03_design/aggregate-redesign.md - 集約の再設計
• reports/03_design/bounded-contexts-redesign.md - 境界コンテキスト

推奨（/analyze-system の出力）:

• reports/01_analysis/system-overview.md - システム概要

出力先

結果は reports/03_design/ に出力します：

• scalardb-architecture.md - アーキテクチャ設計
• scalardb-schema.md - ScalarDBスキーマ設計
• scalardb-transaction.md - トランザクション設計
• scalardb-migration.md - マイグレーション計画

重要: 各ステップ完了時に即座にファイルを出力してください。

ScalarDB概要

ScalarDBは、異種データベース間で分散トランザクションを実現するデータ管理プラットフォームです。エディションによりデプロイモードが異なります。

エディション別デプロイモード

| エディション | デプロイモード | 説明 | |------------|-------------|------| | OSS/Community | 組み込み（Embedded） | Javaライブラリとしてアプリケーションに直接組み込み | | Enterprise Standard | Cluster | gRPCベースの分散トランザクションコーディネーター | | Enterprise Premium | Cluster | Standard + GraphQL + AWS Marketplace対応 |

エディション詳細: .claude/rules/scalardb-edition-profiles.md を参照

ScalarDB Cluster アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                    Application Layer                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │ Service A│ │ Service B│ │ Service C│ │ Service D│       │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘       │
└───────┼────────────┼────────────┼────────────┼──────────────┘
        │  gRPC/SQL  │  GraphQL   │  gRPC      │
        ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────┐
│                  ScalarDB Cluster                            │
│  ┌─────────────────────────────────────────────────────┐    │
│  │            Transaction Coordinator                   │    │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐            │    │
│  │  │ Node 1   │ │ Node 2   │ │ Node 3   │ (HA構成)   │    │
│  │  └──────────┘ └──────────┘ └──────────┘            │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
        │            │            │            │
        ▼            ▼            ▼            ▼
┌─────────────────────────────────────────────────────────────┐
│                    Storage Layer                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐       │
│  │PostgreSQL│ │ DynamoDB │ │ Cassandra│ │  MySQL   │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────┘

主要機能

| 機能 | 説明 | |-----|------| | Consensus Commit | 単一ストレージでのACIDトランザクション | | Two-Phase Commit | 複数ストレージ間の分散トランザクション | | Multi-Storage Transaction | 異種DB間のアトミック操作 | | gRPC API | 高性能なサービス間通信 | | SQL Interface | JDBC互換のSQLアクセス | | GraphQL Interface | 柔軟なクエリAPI | | Vector Search | AIアプリケーション向けベクトル検索 | | High Availability | クラスター構成による高可用性 |

サポートストレージ

| カテゴリ | データベース | |---------|------------| | JDBC | MySQL, PostgreSQL, Oracle, SQL Server, Db2 | | NoSQL | Cassandra, DynamoDB, Cosmos DB, YugabyteDB | | Object Storage | S3, Azure Blob, GCS |

ScalarDB Cluster のメリット

| 観点 | メリット | |-----|---------| | 運用 | 集中管理、統一的な監視・ログ | | スケーラビリティ | ノード追加による水平スケール | | セキュリティ | 認証・認可の一元化 | | マルチテナント | 名前空間による論理分離 | | 開発効率 | SQL/GraphQLによる簡易アクセス |

実行プロンプト

あなたはScalarDB Clusterを使用したマイクロサービスデータアーキテクチャの設計専門家です。以下の手順で設計を実行してください。

Step 0: 前提条件の検証

重要: 実行前に必ず前提条件を確認してください。

必須ファイルの確認:
└── reports/03_design/target-architecture.md  [必須] ← /design-microservices

推奨ファイルの確認:
├── reports/03_design/aggregate-redesign.md      [推奨] ← /ddd-redesign
├── reports/03_design/bounded-contexts-redesign.md [推奨] ← /ddd-redesign
└── reports/01_analysis/system-overview.md       [推奨] ← /analyze-system

エラーハンドリング:

• 必須ファイルが存在しない場合 → /design-microservices を先に実行するよう案内
• 推奨ファイルが存在しない場合 → 警告を表示して続行

Step 1: エディション別ワークフロー分岐

work/{project}/scalardb-edition-config.md を読み込み、エディションに応じてワークフローを分岐する。

• 設定ファイルが存在する場合: edition フィールドを読み込み、以下のルールに従う
• 設定ファイルが存在しない場合: Enterprise Standardをデフォルトとし、全ステップ実行

OSS/Community Edition（組み込みモード）の調整

| ステップ | Enterprise (Cluster) | OSS (Embedded) | |---------|---------------------|----------------| | Step 2: 現状分析 | 実行 | 実行（変更なし） | | Step 4: Cluster構成設計 | 実行 | スキップ — Cluster不要 | | Step 5: ストレージバックエンド設計 | 実行 | 実行（OSS対応ストレージに限定） | | Step 6: スキーマ設計 | 実行 | 実行（変更なし） | | Step 7: トランザクション設計 | 実行 | 実行（Core API例に置換） | | Step 8: 例外処理設計 | 実行 | 実行（変更なし） | | Step 9: パフォーマンス最適化 | 実行 | 実行（Helm設定を除外） | | Step 10: マイグレーション計画 | 実行 | 実行（ライブラリ組み込み設定に置換） |

OSS版の制約:

• SQL Interface / Spring Data JDBC / GraphQL は使用不可 → Core API のみ
• 認証・認可は組み込み未提供 → アプリケーション側で実装
• 対応ストレージ: PostgreSQL, MySQL (JDBC), DynamoDB, Cosmos DB, Cassandra
• 設定テンプレート: .claude/rules/scalardb-edition-profiles.md §2A を使用

Step 2: 現状分析

現在のデータアーキテクチャを分析：

## 現状分析

### データソース一覧
| データソース | 種別 | 用途 | データ量 | トランザクション要件 |
|-------------|-----|------|---------|-------------------|

### クロスサービストランザクション
| トランザクション名 | 関連サービス | 整合性要件 | 現状の実装 |
|------------------|-------------|-----------|-----------|

### 課題
- [課題1]
- [課題2]

Step 3: 非機能要件の確認

データアーキテクチャに影響する非機能要件をAskUserQuestionで確認する。

{
  "questions": [
    {
      "question": "トランザクションの整合性レベル要件を選択してください",
      "header": "整合性",
      "options": [
        {"label": "SERIALIZABLE (推奨)", "description": "最高の整合性。金融・在庫等のミッションクリティカルなデータ向き"},
        {"label": "SNAPSHOT", "description": "読み取り一貫性。書き込み競合時のみ直列化。NoSQL系のデフォルト"},
        {"label": "混在", "description": "サービスごとに異なる整合性レベルを適用"}
      ],
      "multiSelect": false
    },
    {
      "question": "主要なワークロード特性を選択してください",
      "header": "ワークロード",
      "options": [
        {"label": "バランス型 (推奨)", "description": "読み書き比率がほぼ同等。標準的な業務アプリ"},
        {"label": "読み取りヘビー", "description": "読み取りが80%以上。キャッシュ戦略を重視"},
        {"label": "書き込みヘビー", "description": "書き込みが50%以上。バッチ・ログ系"},
        {"label": "混在", "description": "サービスごとに異なるワークロード特性"}
      ],
      "multiSelect": false
    },
    {
      "question": "データ保持・アーカイブの要件を選択してください",
      "header": "データ保持",
      "options": [
        {"label": "オンライン保持のみ (推奨)", "description": "全データをアクティブストレージに保持"},
        {"label": "期間ベースアーカイブ", "description": "一定期間後にコールドストレージへ移動"},
        {"label": "論理削除+物理削除ポリシー", "description": "GDPR等コンプライアンス対応"},
        {"label": "イベントソーシング", "description": "全変更履歴を永続保持"}
      ],
      "multiSelect": false
    }
  ]
}

設計への反映:

• 整合性 → ScalarDB設定の isolation_level / serializable_strategy に反映
• ワークロード → ストレージ選定（Step 5）、パフォーマンス最適化（Step 9）に反映
• データ保持 → スキーマ設計（Step 6）に deleted_at, archived_at カラム追加検討

Step 4: ScalarDB Cluster構成設計

ScalarDB Clusterのクラスター構成を設計します。

構成パターン

シングルリージョン構成（推奨開始構成）

# 構成
- クラスターノード数: 3（奇数推奨）
- ロードバランサー: L4/L7
- 認証: Kubernetes ServiceAccount / OAuth2

# 適用
- 単一リージョンでの高可用性
- 低レイテンシー要件

マルチリージョン構成（災害対策）

# 構成
- プライマリリージョン: 3ノード
- セカンダリリージョン: 3ノード（レプリカ）
- グローバルロードバランサー

# 適用
- 地理的冗長性が必要
- RPO/RTO要件が厳しい

クラスターサイジング

| 規模 | ノード数 | CPU/ノード | メモリ/ノード | 想定TPS | |-----|---------|-----------|-------------|---------| | Small | 3 | 2 vCPU | 4 GB | ~1,000 | | Medium | 5 | 4 vCPU | 8 GB | ~5,000 | | Large | 7+ | 8 vCPU | 16 GB | ~10,000+ |

接続方式の選択

| 方式 | ユースケース | 特徴 | |-----|------------|-----| | gRPC API | 高性能トランザクション | 低レイテンシー、型安全 | | SQL Interface | 既存JDBC資産活用 | 移行容易、標準SQL | | GraphQL | フロントエンド直接アクセス | 柔軟なクエリ、自動生成スキーマ |

graph TB
    subgraph "Application Services"
        A["Order Service<br/>gRPC"]
        B["Inventory Service<br/>gRPC"]
        C["Analytics<br/>SQL"]
        D["BFF<br/>GraphQL"]
    end

    subgraph "ScalarDB Cluster"
        LB[Load Balancer]
        N1[Node 1]
        N2[Node 2]
        N3[Node 3]
    end

    A --> LB
    B --> LB
    C --> LB
    D --> LB
    LB --> N1
    LB --> N2
    LB --> N3

Step 5: ストレージバックエンド設計

各マイクロサービスに適したストレージを選定：

## ストレージ選定

### サービス別ストレージマッピング
| サービス | 主ストレージ | 選定理由 | ScalarDB設定 |
|---------|------------|---------|--------------|
| Order Service | PostgreSQL | トランザクション重視 | JDBC |
| Inventory Service | DynamoDB | スケーラビリティ | DynamoDB Native |
| Analytics Service | Cassandra | 書き込み性能 | Cassandra Native |

### マルチストレージ構成
```mermaid
graph TB
    subgraph "ScalarDB Cluster"
        Coordinator[Transaction Coordinator]
    end

    subgraph Services
        OrderSvc[Order Service]
        InvSvc[Inventory Service]
        PaySvc[Payment Service]
    end

    subgraph Storage
        PG[(PostgreSQL)]
        DDB[(DynamoDB)]
        Cassandra[(Cassandra)]
    end

    OrderSvc --> Coordinator
    InvSvc --> Coordinator
    PaySvc --> Coordinator

    Coordinator --> PG
    Coordinator --> DDB
    Coordinator --> Cassandra

### Step 6: スキーマ設計

ScalarDBのスキーマ設計原則に従ってテーブルを設計：

```markdown
## スキーマ設計

### 命名規則
- Namespace: [service_name]
- Table: [entity_name]
- パーティションキー: ビジネスID（例：order_id, customer_id）
- クラスタリングキー: 時系列やバージョン

### テーブル定義

#### [Namespace].[Table]

| カラム名 | データ型 | キー種別 | 説明 |
|---------|---------|---------|------|
| id | TEXT | PARTITION | 主キー |
| created_at | TIMESTAMP | CLUSTERING | 作成日時 |
| status | TEXT | - | ステータス |
| data | TEXT | - | JSONデータ |

**スキーマJSON:**
```json
{
  "namespace": "order_service",
  "table": "orders",
  "partition_key": ["order_id"],
  "clustering_key": ["created_at"],
  "columns": {
    "order_id": "TEXT",
    "created_at": "TIMESTAMP",
    "customer_id": "TEXT",
    "status": "TEXT",
    "total_amount": "BIGINT"
  },
  "secondary_index": ["customer_id"]
}

### Step 7: トランザクション設計

#### 単一ストレージトランザクション（Consensus Commit）

```java
// 設定
scalar.db.transaction_manager=consensus-commit
scalar.db.storage=jdbc
scalar.db.contact_points=jdbc:postgresql://localhost:5432/mydb

// 使用パターン
DistributedTransactionManager manager = ...;
DistributedTransaction tx = manager.start();
try {
    // Get
    Optional<Result> result = tx.get(Get.newBuilder()
        .namespace("order_service")
        .table("orders")
        .partitionKey(Key.ofText("order_id", orderId))
        .build());

    // Put
    tx.put(Put.newBuilder()
        .namespace("order_service")
        .table("orders")
        .partitionKey(Key.ofText("order_id", orderId))
        .textValue("status", "CONFIRMED")
        .build());

    tx.commit();
} catch (Exception e) {
    tx.rollback();
    throw e;
}

マルチストレージトランザクション（Two-Phase Commit）

// 設定
scalar.db.transaction_manager=consensus-commit
scalar.db.multi_storage.storages=postgres,dynamodb

// PostgreSQL設定
scalar.db.multi_storage.storages.postgres.storage=jdbc
scalar.db.multi_storage.storages.postgres.contact_points=jdbc:postgresql://...

// DynamoDB設定
scalar.db.multi_storage.storages.dynamodb.storage=dynamo
scalar.db.multi_storage.storages.dynamodb.contact_points=dynamodb.ap-northeast-1.amazonaws.com

// Namespace-Storage マッピング
scalar.db.multi_storage.namespace_mapping=order_service:postgres,inventory_service:dynamodb

Sagaパターン（長時間トランザクション）

## Sagaオーケストレーション

### 注文作成Saga
1. Order Service: 注文を作成（PENDING）
2. Inventory Service: 在庫を予約
3. Payment Service: 決済を実行
4. Order Service: 注文を確定（CONFIRMED）

### 補償トランザクション
| ステップ | 正常処理 | 補償処理 |
|---------|---------|---------|
| 在庫予約 | reserveInventory() | releaseInventory() |
| 決済実行 | processPayment() | refundPayment() |
| 注文確定 | confirmOrder() | cancelOrder() |

sequenceDiagram
    participant Client
    participant OrderSvc as Order Service
    participant InvSvc as Inventory Service
    participant PaySvc as Payment Service
    participant ScalarDB as ScalarDB Cluster

    Client->>OrderSvc: 注文作成
    OrderSvc->>ScalarDB: Begin 2PC
    ScalarDB->>OrderSvc: TX Started

    OrderSvc->>ScalarDB: Insert Order (PENDING)
    OrderSvc->>InvSvc: Reserve Inventory
    InvSvc->>ScalarDB: Update Inventory

    OrderSvc->>PaySvc: Process Payment
    PaySvc->>ScalarDB: Insert Payment

    OrderSvc->>ScalarDB: Prepare
    ScalarDB-->>OrderSvc: Prepared

    OrderSvc->>ScalarDB: Commit
    ScalarDB-->>OrderSvc: Committed

    OrderSvc->>Client: 注文完了

Step 8: 例外処理設計

ScalarDBの例外カテゴリに基づく処理戦略：

| 例外タイプ | 例外クラス | 対応戦略 | |----------|----------|---------| | Transient | CrudConflictException | リトライ（指数バックオフ） | | Transient | CommitConflictException | リトライ（指数バックオフ） | | Non-Transient | CrudException | 根本原因調査、エラー返却 | | Unknown | UnknownTransactionStatusException | 冪等性チェック後リトライ |

// リトライパターン
int maxRetries = 3;
for (int i = 0; i < maxRetries; i++) {
    try {
        executeTransaction();
        break;
    } catch (CrudConflictException | CommitConflictException e) {
        if (i == maxRetries - 1) throw e;
        Thread.sleep((long) Math.pow(2, i) * 100);
    } catch (UnknownTransactionStatusException e) {
        // 冪等性キーでコミット状態を確認
        if (isAlreadyCommitted(idempotencyKey)) {
            return getExistingResult(idempotencyKey);
        }
        throw e;
    }
}

Step 9: パフォーマンス最適化

Group Commit（書き込み最適化）

# 有効化
scalar.db.consensus_commit.coordinator.group_commit.enabled=true

# スロットサイズ（並列書き込み数）
scalar.db.consensus_commit.coordinator.group_commit.slot_capacity=20

# 遅延時間（ミリ秒）
scalar.db.consensus_commit.coordinator.group_commit.group_size_fix_timeout_millis=20

Implicit Pre-Read

// 存在チェックを自動化
Put put = Put.newBuilder()
    .namespace("order_service")
    .table("orders")
    .partitionKey(Key.ofText("order_id", orderId))
    .textValue("status", "CONFIRMED")
    .enableImplicitPreRead()  // 自動で存在チェック
    .build();

Step 10: マイグレーション計画

## マイグレーション計画

### Phase 1: 準備
- ScalarDB Cluster環境構築
- Coordinatorテーブル作成
- スキーマ定義とテーブル作成

### Phase 2: Shadow Migration
- 既存DBとScalarDB双方に書き込み
- データ整合性検証
- パフォーマンス計測

### Phase 3: 段階的切り替え
| サービス | 切り替え順 | 前提条件 | ロールバック計画 |
|---------|----------|---------|----------------|
| Master Data | 1 | - | 旧DB復元 |
| Order Service | 2 | Master完了 | フラグ切り替え |
| Payment Service | 3 | Order完了 | フラグ切り替え |

### Phase 4: 完全移行
- 旧DB参照の削除
- モニタリング強化
- ドキュメント更新

Step 11: Mermaid図の検証

出力したファイルのMermaid図を検証し、エラーがあれば修正：

/fix-mermaid ./reports/03_design

出力フォーマット

scalardb-architecture.md

ScalarDB Clusterアーキテクチャ設計：

• クラスター構成（ノード数、リージョン構成）
• 接続方式（gRPC/SQL/GraphQL）
• ストレージ構成
• ネットワーク設計
• セキュリティ設計（認証・認可）
• Kubernetes/Helmデプロイ設定

scalardb-schema.md

スキーマ設計：

• Namespace一覧
• テーブル定義
• インデックス設計
• パーティション戦略

scalardb-transaction.md

トランザクション設計：

• トランザクションパターン
• Saga設計
• 例外処理戦略
• 冪等性設計

scalardb-migration.md

マイグレーション計画：

• フェーズ別計画
• データ移行手順
• 検証計画
• ロールバック手順

ツール活用ガイドライン

設計図作成

• Mermaid記法を使用
• アーキテクチャ図、シーケンス図を作成
• ER図でスキーマを可視化

コード確認

# 既存のデータアクセスパターンを確認
mcp__serena__find_symbol で Repository/DAO クラスを検索
mcp__serena__find_referencing_symbols でトランザクション境界を確認

設定ファイルテンプレート

ScalarDB Cluster サーバー設定

# scalardb-cluster-node.properties テンプレート

# Cluster設定
scalar.db.cluster.node.standalone_mode.enabled=false
scalar.db.cluster.membership.type=KUBERNETES

# gRPC設定
scalar.db.cluster.grpc.deadline_duration_millis=60000

# トランザクション設定
scalar.db.storage=multi-storage
scalar.db.transaction_manager=consensus-commit

# Coordinator設定
scalar.db.consensus_commit.coordinator.namespace=coordinator
scalar.db.consensus_commit.coordinator.group_commit.enabled=true

# マルチストレージ設定
scalar.db.multi_storage.storages=postgres,dynamodb,cassandra
scalar.db.multi_storage.namespace_mapping=order_service:postgres,inventory_service:dynamodb

# 認証設定
scalar.db.cluster.auth.enabled=true
scalar.db.cluster.auth.type=JWT

クライアント設定

# scalardb-cluster-client.properties

# Cluster接続
scalar.db.contact_points=indirect:scalardb-cluster-headless.default.svc.cluster.local
scalar.db.contact_port=60053

# 認証
scalar.db.cluster.auth.enabled=true
scalar.db.cluster.auth.credential.type=JWT

Kubernetes Helm Values

# values.yaml (Helm Chart)
scalardbCluster:
  replicaCount: 3

  resources:
    requests:
      cpu: "2"
      memory: "4Gi"
    limits:
      cpu: "4"
      memory: "8Gi"

  scalardbClusterNodeProperties: |
    scalar.db.cluster.membership.type=KUBERNETES
    scalar.db.storage=multi-storage
    # ... 追加設定

  envoy:
    enabled: true
    replicaCount: 3

アンチパターン

避けるべき設計

| アンチパターン | 問題 | 推奨 | |--------------|-----|-----| | クロスパーティションスキャン多用 | パフォーマンス低下 | セカンダリインデックス活用 | | 大きなトランザクション | ロック競合 | トランザクション分割 | | Group Commit + カスタムTX ID | 未サポート | 自動生成ID使用 | | 非JDBC DBでSERIALIZABLE前提 | SNAPSHOTになる可能性 | 整合性レベル確認 |

エラーハンドリング

• エディション未選定 → /select-scalardb-edition を先に実行するよう案内
• Context7で最新情報が取得できない場合 → .claude/rules/scalardb-edition-profiles.md の静的情報で設計
• DDD設計が未実施 → 対象パスのコード解析からドメイン境界を推定（精度低下を警告）
• ストレージバックエンドが未定 → PostgreSQLをデフォルトで設計し、後から変更可能と案内

関連スキル

| スキル | 用途 | |-------|-----| | /design-scalardb-analytics | 分析基盤設計（レポート、ダッシュボード、クロスDBクエリ） | | /design-microservices | マイクロサービスアーキテクチャ設計 | | /map-domains | ドメイン境界・コンテキスト設計 |

参考資料

• ScalarDB Documentation
• ScalarDB Analytics
• ScalarDB GitHub
• ScalarDB Samples