design-scalardb

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

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   │       │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘       │
└─────────────────────────────────────────────────────────────┘

主要機能

機能	説明
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 1: 現状分析

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

## 現状分析

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

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

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

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

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

ストレージ選定

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

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

マルチストレージ構成

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

例外タイプ	例外クラス	対応戦略
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 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

アンチパターン

避けるべき設計

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

関連スキル

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

参考資料

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