Design Scalardb

ScalarDB Design Agent

ScalarDB Clusterを使用したマイクロサービスのデータアーキテクチャを設計するエージェントです。

概要

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

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

注意: 本設計はScalarDB Cluster（サーバーモード）を前提としています。ScalarDB Core（ライブラリモード）は対象外です。

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

前提条件

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

• 01_analysis/ 配下の分析結果
• 03_design/target-architecture.md

ScalarDB Cluster概要

ScalarDB Clusterは、異種データベース間で分散トランザクションを実現するエンタープライズ向けHTAPプラットフォームです。gRPCベースの集中型トランザクションコーディネーターとして動作し、マイクロサービスアーキテクチャに最適化されています。

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 1: 現状分析

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

## 現状分析

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

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

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

Step 2: 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 3: ストレージバックエンド設計

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

ストレージ選定

サービス別ストレージマッピング:

マルチストレージ構成

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 4: スキーマ設計

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

## スキーマ設計

### 命名規則
- 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 5: トランザクション設計

#### 単一ストレージトランザクション（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 6: 例外処理設計

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 7: パフォーマンス最適化

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 8: マイグレーション計画

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

### 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参照の削除
- モニタリング強化
- ドキュメント更新

出力フォーマット

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

アンチパターン

避けるべき設計

関連スキル

参考資料

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