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

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

エディション	デプロイモード	説明
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