design-scalardb

name: design-scalardb description: ScalarDB設計エージェント - エディション設定に基づくマイクロサービスのデータアーキテクチャ設計。分散トランザクション、スキーマ設計、ポリグロット永続化を策定。/design-scalardb [対象パス] で呼び出し。 user_invocable: true

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

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

エディション詳細: .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   │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────┘

主要機能

サポートストレージ

ScalarDB Cluster のメリット

実行プロンプト

あなたは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（組み込みモード）の調整

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要件が厳しい

クラスターサイジング

接続方式の選択

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の例外カテゴリに基づく処理戦略：

// リトライパターン
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

アンチパターン

避けるべき設計

エラーハンドリング

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

関連スキル

参考資料

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