voltdb-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

VoltDB Development

VoltDB 开发

This skill creates complete VoltDB client applications with optimized partitioning. It generates Maven project scaffolding, analyzes data models for partitioning strategy, creates DDL schemas and stored procedures, and produces integration tests with testcontainer support.

该Skill可创建带有优化分区的完整VoltDB客户端应用，它会生成Maven项目脚手架，分析数据模型以制定分区策略，创建DDL schema和存储过程，并生成支持testcontainer的集成测试。

Rules

规则

Rules are organized in the

rules/

directory. Read only the rule files needed for the current phase — do NOT read all rules upfront.

Priority	Category	Impact	Rule Files
1	Partitioning Strategy	HIGH	rules/part-critical-rules.md, rules/part-choose-column.md, rules/part-colocation.md, rules/part-lookup-tables.md
2	DDL & Stored Procedures	HIGH	rules/ddl-procedures.md
3	Project Setup	MEDIUM	rules/proj-setup.md
4	Integration Testing	MEDIUM	rules/test-base-class.md, rules/test-data-and-patterns.md
5	Workflow & Templates	MEDIUM	rules/workflow-readme-template.md

规则统一存放在

rules/

目录下，仅读取当前阶段所需的规则文件，请勿提前读取所有规则。

优先级	分类	影响程度	规则文件
1	分区策略	高	rules/part-critical-rules.md, rules/part-choose-column.md, rules/part-colocation.md, rules/part-lookup-tables.md
2	DDL与存储过程	高	rules/ddl-procedures.md
3	项目搭建	中	rules/proj-setup.md
4	集成测试	中	rules/test-base-class.md, rules/test-data-and-patterns.md
5	工作流与模板	中	rules/workflow-readme-template.md

Workflow

工作流

Use the
AskUserQuestion
tool for each question. This provides clickable options for the user.

所有问题都请使用
AskUserQuestion
工具发起，这会为用户提供可点击的选项。

Step 1: Verify Prerequisites

步骤1：验证前置依赖

Before starting any work, verify that all required infrastructure is available. Run these checks using Bash:

bash

undefined

在开始任何工作前，请先验证所有必需的基础环境是否可用，使用Bash运行以下检查命令：

bash

undefined

Check Docker is running

docker info > /dev/null 2>&1


- **If Docker is NOT running:** Stop and use `AskUserQuestion` to tell the user:
  - **question:** "Docker is required but not running. Please start Docker and let me know when it's ready."
  - **header:** "Docker"
  - **options:**
    - `Docker is running now` - I've started Docker
    - `Help me start Docker` - Show me how to start it
  - If user selects "Help me start Docker", provide platform-specific instructions:
    - macOS: `open -a Docker`
    - Linux: `sudo systemctl start docker`
  - After user confirms Docker is running, re-verify with `docker info` before proceeding.

```bash

docker info > /dev/null 2>&1


- **如果Docker未运行：** 停止后续操作，使用`AskUserQuestion`告知用户：
  - **question:** "Docker是必需工具但当前未运行，请启动Docker并在准备就绪后告知我。"
  - **header:** "Docker"
  - **options:**
    - `Docker is running now` - 我已经启动了Docker
    - `Help me start Docker` - 教我怎么启动Docker
  - 如果用户选择"Help me start Docker"，提供对应平台的启动指令：
    - macOS: `open -a Docker`
    - Linux: `sudo systemctl start docker`
  - 用户确认Docker已运行后，在继续操作前请重新运行`docker info`验证环境正常。

```bash

Check Java 17+

java -version 2>&1


- **If Java is not available or below version 17:** Inform the user and stop.

```bash

java -version 2>&1


- **如果Java不可用或者版本低于17：** 告知用户并停止操作。

```bash

Check Maven 3.6+

mvn -version 2>&1


- **If Maven is not available:** Inform the user and stop.

**Only proceed to Step 2 after all prerequisites pass.**

mvn -version 2>&1


- **如果Maven不可用：** 告知用户并停止操作。

**所有前置依赖检查通过后，才可进入步骤2。**

Step 2: Ask License Location

步骤2：询问许可证位置

VoltDB Enterprise requires a license file. Use

AskUserQuestion

with:

question: "Where is your VoltDB Enterprise license file?"
header: "License"
options:
- ```
VOLTDB_LICENSE env var
```
  (Recommended) - I have VOLTDB_LICENSE environment variable set
- ```
/tmp/voltdb-license.xml
```
  - License is at the default location
- ```
Specify path
```
  - I'll provide the path to my license file

After the user responds:

VOLTDB_LICENSE env var

: run

echo $VOLTDB_LICENSE

and verify the file exists at that path using

test -f "$VOLTDB_LICENSE"

/tmp/voltdb-license.xml

: verify the file exists using

test -f /tmp/voltdb-license.xml

If
```
Specify path
```
: ask the user for the path, then verify the file exists.

If the license file is not found at the specified location, inform the user and ask them to correct the path. Do not proceed until a valid license file is confirmed.

Save the confirmed license path — it will be used when generating

test.properties

VoltDB企业版需要许可证文件，使用

AskUserQuestion

发起询问，参数如下：

question: "你的VoltDB企业版许可证文件存放在哪里？"
header: "许可证"
options:
- ```
VOLTDB_LICENSE env var
```
  （推荐） - 我已经设置了VOLTDB_LICENSE环境变量
- ```
/tmp/voltdb-license.xml
```
  - 许可证存放在默认位置
- ```
Specify path
```
  - 我会提供许可证文件的路径

用户回复后：

如果选择
```
VOLTDB_LICENSE env var
```
：运行
```
echo $VOLTDB_LICENSE
```
，并使用
```
test -f "$VOLTDB_LICENSE"
```
验证该路径下的文件是否存在。

如果选择

/tmp/voltdb-license.xml

：使用

test -f /tmp/voltdb-license.xml

验证文件是否存在。

如果选择
```
Specify path
```
：询问用户许可证路径，然后验证文件是否存在。

如果指定路径下未找到许可证文件，告知用户并要求其修正路径，在确认获取到有效许可证文件前请勿继续操作。

保存确认后的许可证路径，生成

test.properties

时会用到该路径。

Step 3: Ask Application Name

步骤3：询问应用名称

Use

AskUserQuestion

with:

question: "What should the application be called?"
header: "App name"
options:
- ```
my-voltdb-app
```
  (Recommended)
- ```
voltdb-client
```
- ```
data-service
```

User can select an option or type their own.

使用

AskUserQuestion

发起询问，参数如下：

question: "应用的名称是什么？"
header: "应用名称"
options:
- ```
my-voltdb-app
```
  （推荐）
- ```
voltdb-client
```
- ```
data-service
```

用户可以选择已有选项，也可以输入自定义名称。

Step 4: Ask Output Directory

步骤4：询问输出目录

Use

AskUserQuestion

with:

question: "Where should I create the project?"
header: "Directory"
options:
- ```
Current directory
```
  (Recommended)
- ```
Specify path
```
  - I'll provide a path

使用

AskUserQuestion

发起询问，参数如下：

question: "我应该在哪个路径下创建项目？"
header: "目录"
options:
- ```
Current directory
```
  （推荐）
- ```
Specify path
```
  - 我会提供存储路径

Step 5: Ask Data Model

步骤5：询问数据模型

Use

AskUserQuestion

with:

question: "What type of data model do you need?"
header: "Data model"
options:
- ```
Describe custom tables
```
  - I'll describe my tables and columns
- ```
Use example model
```
  - Customer/Orders/Product example
- ```
Key-Value store
```
  - Simple key-value table (no partitioning analysis needed)

If user selects "Describe custom tables", ask them to describe their tables in a follow-up message.

使用

AskUserQuestion

发起询问，参数如下：

question: "你需要什么类型的数据模型？"
header: "数据模型"
options:
- ```
Describe custom tables
```
  - 我会描述我的表和字段信息
- ```
Use example model
```
  - 使用客户/订单/产品示例模型
- ```
Key-Value store
```
  - 简单键值表（无需进行分区分析）

如果用户选择"Describe custom tables"，在后续消息中请用户描述其表结构信息。

Step 6: Analyze and Generate

步骤6：分析与生成

Phase 1 — Partitioning Analysis (skip for Key-Value):

Read rules/part-critical-rules.md and rules/part-choose-column.md
If co-location is needed, read rules/part-colocation.md
If cross-domain queries exist, read rules/part-lookup-tables.md
Recommend partition column, co-location groups, lookup tables, and procedure types
Present strategy for user confirmation using
```
AskUserQuestion
```
:
- question: "Does this partitioning strategy work for you? [strategy summary]"
- header: "Strategy"
- options:
  - ```
  Yes, proceed
```
  (Recommended)
- ```
Modify strategy
```
    - I want to change something
  - ```
  Explain more
```
  - Tell me more about the trade-offs

Phase 2 — Code Generation:

Read rules/proj-setup.md → create Maven project structure +
```
pom.xml
```

Read rules/ddl-procedures.md → generate:

src/main/resources/ddl.sql

(with

DROP PROCEDURE IF EXISTS

pattern)

```
src/main/resources/remove_db.sql
```
(DROP in dependency order)
Stored procedures under
```
src/main/java/[package]/procedures/
```

Generate
```
[AppName]App.java
```
— main client app (rules/proj-setup.md template)
Generate
```
VoltDBSetup.java
```
— schema deployment (rules/proj-setup.md template)
Generate
```
CsvDataLoader.java
```
— CSV loading utility (rules/test-data-and-patterns.md template)
Generate CSV data files in
```
src/main/resources/data/
```
(rules/test-data-and-patterns.md)
Read rules/test-base-class.md → generate
```
IntegrationTestBase.java
```
Read rules/test-data-and-patterns.md → generate
```
[TestName]IT.java
```
Generate
```
test.properties
```
at
```
src/test/resources/test.properties
```
with testcontainer mode, shutdown enabled, and the confirmed license path from Step 2
Read rules/workflow-readme-template.md → generate project
```
README.md
```

Auto-derived defaults (no questions asked):

Package name:
```
com.example.voltdb
```
VoltDB connection mode: testcontainer
Testcontainer shutdown: yes

阶段1 — 分区分析（键值存储场景跳过）：

读取rules/part-critical-rules.md和rules/part-choose-column.md
如果需要同位置部署，读取rules/part-colocation.md
如果存在跨域查询，读取rules/part-lookup-tables.md
推荐分区字段、同位置部署组、查找表和存储过程类型
使用
```
AskUserQuestion
```
向用户展示分区策略并请求确认：
- question: "该分区策略是否符合你的需求？[策略摘要]"
- header: "分区策略"
- options:
  - ```
  Yes, proceed
```
  （推荐）
- ```
Modify strategy
```
    - 我要修改部分内容
  - ```
  Explain more
```
  - 告诉我更多相关的取舍权衡

阶段2 — 代码生成：

读取rules/proj-setup.md → 创建Maven项目结构 +
```
pom.xml
```
读取rules/ddl-procedures.md → 生成：
- ```
src/main/resources/ddl.sql
```
  （采用
```
DROP PROCEDURE IF EXISTS
```
  写法）
- ```
src/main/resources/remove_db.sql
```
  （按依赖顺序执行DROP操作）
- 存放在
```
src/main/java/[包名]/procedures/
```
  下的存储过程
生成
```
[AppName]App.java
```
— 主客户端应用（遵循rules/proj-setup.md模板）
生成
```
VoltDBSetup.java
```
— schema部署工具（遵循rules/proj-setup.md模板）
生成
```
CsvDataLoader.java
```
— CSV数据加载工具（遵循rules/test-data-and-patterns.md模板）
在
```
src/main/resources/data/
```
下生成CSV数据文件（遵循rules/test-data-and-patterns.md）
读取rules/test-base-class.md → 生成
```
IntegrationTestBase.java
```
读取rules/test-data-and-patterns.md → 生成
```
[TestName]IT.java
```
在
```
src/test/resources/test.properties
```
下生成配置文件，包含testcontainer模式、开启自动关闭，以及步骤2中确认的许可证路径
读取rules/workflow-readme-template.md → 生成项目
```
README.md
```

自动使用的默认值（无需询问用户）：

包名：
```
com.example.voltdb
```
VoltDB连接模式：testcontainer
Testcontainer自动关闭：开启

Step 7: Build and Test

步骤7：构建与测试

After generating the project, automatically build and test:

bash

cd <project-name> && mvn clean package -DskipTests && mvn verify

If the build fails, diagnose the error and fix it. If it succeeds, report the results to the user.

项目生成完成后，自动执行构建和测试：

bash

cd <project-name> && mvn clean package -DskipTests && mvn verify

如果构建失败，诊断错误并修复；如果构建成功，向用户反馈运行结果。