DataClawe — Database as a Utility

DCL — DataClawe 命令语言

一种基于 JSON 的数据库命令标准，面向 AI Agent、前端工程师，以及觉得 SQL 太复杂的任何人。

“如果你懂 MySQL 和 MSX-BASIC，就已经懂 DCL 了。”

---

什么是 DCL？

DCL（DataClawe Command Language，DataClawe 命令语言）是一种开放标准，可通过简单的 JSON 与数据库通信。

它专为以下场景设计：

• AI Agent（Claude、GPT、Cursor 等）安全地读取和写入结构化数据
• 前端工程师无需编写 SQL 即可访问数据库
• **MCP（Model Context Protocol）**工具集成
• 任何应用连接 MySQL 或 PostgreSQL——无论是现有应用还是新应用

DCL 会在内部转换为原生 SQL。现有数据库无需更改，现有应用也无需更改。

---

设计理念

DCL 遵循三条规则：

1. 看得懂，就能理解。 没有晦涩的运算符，没有特定框架的语法，也没有 : 链式写法。

2. MySQL 词汇，JSON 结构。 SELECT、INSERT、UPDATE、DELETE 等操作正如你所预期。WHERE 条件采用 MySQL 工程师熟悉的写法。

3. MSX-BASIC 级别的简单。 如果 age >= 20 这样的条件还需要解释，那就是设计失败了。

4. 默认简单，需要时强大。 标准功能涵盖大多数实际需求，高级功能则覆盖其余需求。只有在需要时，你才需要承担复杂性。

---

快速入门

获取数据

{
  "dcl": "1.0",
  "action": "SELECT",
  "table": "users",
  "columns": ["id", "name", "email"],
  "where": [
    "status = 'active'",
    "age >= 20"
  ],
  "order": "created_at DESC",
  "limit": 10,
  "offset": 0
}

插入记录

{
  "dcl": "1.0",
  "action": "INSERT",
  "table": "users",
  "data": {
    "name": "kimura",
    "email": "[email protected]",
    "status": "active"
  }
}

更新记录

{
  "dcl": "1.0",
  "action": "UPDATE",
  "table": "users",
  "data": {
    "status": "inactive"
  },
  "where": [
    "id = 123"
  ]
}

删除记录（逻辑删除）

{
  "dcl": "1.0",
  "action": "DELETE",
  "table": "users",
  "where": [
    "id = 123"
  ]
}

---

操作

操作	说明	只读
SELECT	获取一条或多条记录	✅
COUNT	统计匹配的记录数	✅
EXISTS	检查记录是否存在	✅
SCHEMA	获取表的列定义	✅
TABLES	列出所有可用表	✅
STATS	获取记录数、最后更新时间和存储大小	✅
TIMELINE	获取记录的按时间顺序排列的变更历史	✅
INSERT	创建新记录	❌
UPDATE	更新现有记录	❌
DELETE	逻辑删除（状态标记）	❌
TABLE_CREATE	创建新表（空声明）	❌
TABLE_COPY	复制表	❌
TABLE_RENAME	重命名表	❌
TABLE_DROP	逻辑删除表	❌

---

WHERE 条件

WHERE 是一个条件字符串数组。默认情况下，多个条件之间使用 AND 连接。

基本比较

"where": [
  "status = 'active'",
  "age >= 20",
  "age <= 60",
  "status != 'deleted'"
]

OR 条件

"where": {
  "OR": [
    "status = 'active'",
    "status = 'pending'"
  ]
}

AND + OR 组合

"where": {
  "AND": [
    "age >= 20",
    {
      "OR": [
        "status = 'active'",
        "status = 'pending'"
      ]
    }
  ]
}

LIKE

"where": [
  "name LIKE 'kimura%'"
]

IN

"where": [
  "status IN ('active', 'pending')"
]

BETWEEN

"where": [
  "age BETWEEN 20 AND 60"
]

NULL 检查

"where": [
  "deleted_at IS NULL"
]

"where": [
  "deleted_at IS NOT NULL"
]

---

聚合

{
  "dcl": "1.0",
  "action": "SELECT",
  "table": "orders",
  "columns": [
    "SUM(amount) AS total",
    "AVG(amount) AS average",
    "COUNT(*) AS count"
  ],
  "where": [
    "status = 'paid'"
  ],
  "group": "customer_id"
}

---

COUNT

{
  "dcl": "1.0",
  "action": "COUNT",
  "table": "users",
  "where": [
    "status = 'active'"
  ]
}

---

EXISTS

{
  "dcl": "1.0",
  "action": "EXISTS",
  "table": "users",
  "where": [
    "email = '[email protected]'"
  ]
}

---

SCHEMA

{
  "dcl": "1.0",
  "action": "SCHEMA",
  "table": "users"
}

---

TABLES

{
  "dcl": "1.0",
  "action": "TABLES"
}

---

TABLE_CREATE — 创建表

声明一个新的空表。内部会创建一条 status=8 的 schema 声明记录。

{
  "dcl": "1.0",
  "action": "TABLE_CREATE",
  "table": "users"
}

可选的 schema 定义：

{
  "dcl": "1.0",
  "action": "TABLE_CREATE",
  "table": "users",
  "schema": {
    "name":  "text",
    "age":   "integer",
    "email": "text"
  }
}

**不指定 schema：**创建时 schema: null。首次 INSERT 时，列类型会自动注册为 text。

---

status=8 Schema 声明记录

DataClawe 会为每张表维护一条 status=8 声明记录。

状态值	用途
status=1	普通记录（有效）
status=8	表声明 + schema 缓存
status=9	已逻辑删除

status=8 记录内容示例：

{
  "schema": {
    "name":  "text",
    "age":   "text",
    "email": "text"
  }
}

Schema 自动演进：

通过 INSERT 写入不存在的表时，会自动创建 status=8 记录。 每次 INSERT 时，新的列都会自动追加到 status=8 schema 中（类型默认为 text）。

First INSERT: {"name": "kimura", "age": 25}
  → Auto-create status=8: {"name":"text", "age":"text"}
  → INSERT the record

Second INSERT: {"name": "suzuki", "phone": "090-xxxx"}
  → "phone" is new → auto-append to status=8 schema
  → schema: {"name":"text", "age":"text", "phone":"text"}

连接到旧版 MySQL/PostgreSQL 时，实际列类型（VARCHAR(255)、INT 等）会记录在 status=8 记录中。

---

STATS — 表统计信息

返回记录数、最后更新时间戳和存储大小。AI Agent 可据此在操作前评估表的状态。

{
  "dcl": "1.0",
  "action": "STATS",
  "table": "users"
}

响应示例：

{
  "dcl": "1.0",
  "status": "OK",
  "data": {
    "table": "users",
    "record_count": 1024,
    "last_updated": "2026-03-28T10:00:00Z",
    "size_kb": 512
  }
}

---

TIMELINE — 记录变更历史

按时间顺序返回记录的变更历史（创建、更新、逻辑删除）。适用于跟踪数据演变的 AI Agent。

{
  "dcl": "1.0",
  "action": "TIMELINE",
  "table": "users",
  "where": [
    "id = 123"
  ]
}

---

TABLE_COPY — 复制表

以新名称复制一张表。用于备份、迁移和测试。

{
  "dcl": "1.0",
  "action": "TABLE_COPY",
  "table": "users",
  "target_table": "users_backup_20260328"
}

---

TABLE_RENAME — 重命名表

重命名一张表。

{
  "dcl": "1.0",
  "action": "TABLE_RENAME",
  "table": "users_old",
  "new_name": "users_archived"
}

---

TABLE_DROP — 删除表（逻辑删除）

逻辑删除一张表。数据不会立即从物理层面移除。

{
  "dcl": "1.0",
  "action": "TABLE_DROP",
  "table": "users_temp"
}

注意： TABLE_DROP 是逻辑删除——不等同于 SQL DROP TABLE。数据不会立即销毁。

---

响应格式

成功

{
  "dcl": "1.0",
  "status": "OK",
  "count": 42,
  "data": [
    { "id": 1, "name": "kimura", "email": "[email protected]" }
  ],
  "meta": {
    "table": "users",
    "elapsed_ms": 12
  }
}

错误

{
  "dcl": "1.0",
  "status": "ERROR",
  "code": "TABLE_NOT_FOUND",
  "message": "Table 'users' does not exist"
}

错误代码

代码	描述
TABLE_NOT_FOUND	指定的表不存在
COLUMN_NOT_FOUND	指定的列不存在
INVALID_ACTION	指定了未知操作
INVALID_WHERE	无法解析 WHERE 条件
PERMISSION_DENIED	租户无权访问
CONNECTION_ERROR	数据库连接失败

---

集成

DCL 支持两种协议。两种协议中的 DCL 命令完全相同。

协议	使用方	指南
REST API（HTTPS POST）	前端、后端、任何 HTTP 客户端	参见 README.api.md
MCP（JSON-RPC 2.0 / SSE）	AI Agent（Claude、GPT、Cursor）	参见 README.mcp.md

DCL 载荷（两种协议中完全相同）

{
  "dcl": "1.0",
  "action": "SELECT",
  "table": "orders",
  "where": [
    "status = 'pending'",
    "created_at >= '2026-01-01'"
  ],
  "order": "created_at DESC",
  "limit": 100
}

无论通过 REST API 还是 MCP 调用，这段 DCL JSON 都相同。只有外层协议层不同。

---

支持的数据库

数据库	状态
MySQL 5.x / 8.x	✅ 支持
PostgreSQL 9–18	✅ 支持
其他	📋 计划中

DCL 会统一 MySQL 和 PostgreSQL 之间的差异。你只需编写一条 DCL 命令，其余工作由 DataClawe 处理。

---

复杂度层级

DCL 采用双层设计。你可以选择所需的层级。

---

DCL Standard — 本规范

适用于 AI Agent、前端工程师，以及任何进行简单数据操作的人员。

• 不支持 JOIN，不支持子查询。
• 任何了解 MySQL 基础知识的人都能读懂。
• 覆盖绝大多数实际 CRUD 需求。

如果 Standard 能满足你的需求，就无需使用更高级的功能。

---

DCL Advanced — 将于 v1.1 推出

适用于需要更强表达能力的后端工程师。

JSON 结构相同。DataClawe 引擎相同。需要时提供更多能力。

JOIN

{
  "dcl": "1.0",
  "action": "SELECT",
  "table": "users",
  "columns": ["users.id", "users.name", "orders.amount"],
  "join": [
    {
      "table": "orders",
      "on": "users.id = orders.user_id",
      "type": "LEFT"
    }
  ],
  "where": [
    "users.status = 'active'"
  ],
  "order": "orders.amount DESC",
  "limit": 20
}

子查询

{
  "dcl": "1.0",
  "action": "SELECT",
  "table": "users",
  "where": [
    "id IN (SELECT user_id FROM orders WHERE status = 'paid')"
  ]
}

多个 JOIN

{
  "dcl": "1.0",
  "action": "SELECT",
  "table": "orders",
  "columns": [
    "orders.id",
    "users.name AS customer",
    "products.name AS product",
    "orders.amount"
  ],
  "join": [
    {
      "table": "users",
      "on": "orders.user_id = users.id",
      "type": "INNER"
    },
    {
      "table": "products",
      "on": "orders.product_id = products.id",
      "type": "LEFT"
    }
  ],
  "where": [
    "orders.status = 'paid'",
    "orders.created_at >= '2026-01-01'"
  ],
  "order": "orders.created_at DESC"
}

Advanced 支持的 JOIN 类型

类型	描述
INNER	两张表中都匹配的记录
LEFT	左表中的所有记录，以及右表中匹配的记录
RIGHT	右表中的所有记录，以及左表中匹配的记录

---

为什么采用双层设计？

SQL solved everything in one spec.
That is why SQL is still hard after 30 years.

DCL Standard is for everyone.
DCL Advanced is for when you need more.
You always start simple. You go deeper only when you must.

两者使用同一套引擎和 JSON 结构。从 Standard 升级到 Advanced 时，无需学习新语法，只需使用新的键。

---

有意不支持的功能

为确保 DCL 对 AI Agent 安全且行为可预测，以下内容不属于 Standard 和 Advanced 的范围：

• 存储过程
• 创建架构或执行 ALTER TABLE
• 原始 SQL 直通
• 物理销毁架构（相当于立即执行 DROP TABLE）

注意： DCL 中的 TABLE_DROP 是逻辑删除，与 SQL DROP TABLE 不同。它不会立即销毁数据。

DCL 是一种数据操作语言，而非架构管理语言。

---

版本控制

每个请求和响应都必须包含 "dcl": "1.0" 字段。

未来版本将保持向后兼容。DCL 1.0 请求始终可以用于 DCL 2.0 服务端。

---

参与贡献

DCL 是一项开放规范。欢迎提供反馈、提案和拉取请求。

• 提交 issue，提议新增操作或运算符
• 提交拉取请求，改进文档或示例
• 所有贡献都必须遵循设计理念：易读、贴近 MySQL、简单到 BASIC 级别

---

路线图

v1.0 — DCL 标准

• 完成规范定稿
• 用于验证的 JSON Schema（dcl.schema.json）
• Go 参考实现（DataClawe Engine）
• MCP 服务参考实现
• 支持 MySQL 线协议
• 多租户隔离规范

v1.1 — DCL 高级功能

• JOIN 规范（INNER / LEFT / RIGHT）
• 支持子查询
• 嵌套聚合

SDK

• JavaScript / TypeScript
• PHP
• Python
• Go

---

定价

DataClawe 采用分级定价模式，适用于个人开发者和企业。

初始注册费：$20（一次性，适用于所有方案）

方案	月费	记录数	会话数	SLA
免费	$0	2,000	100/天	否
个人	$20	最多 20,000	每月最多 20,000	否
商业	$20+	不限	不限	否
企业	联系我们	不限	不限	是

用量费率（商业方案 — 超额用量）

项目	单价
记录存储	$0.001 / 条记录 / 月
会话	$0.001 / 个会话

记录大小限制：每条记录 100KB。 这适用于 IoT 传感器数据、CRM 联系人、医疗文本记录、WordPress 文章和金融交易记录。 图片和视频文件不在适用范围内——请将其存储在 CDN/对象存储中，并在 DataClawe 中保存 URL。

如需了解企业版定价，请通过 dataclawe.com/enterprise 联系我们。

---

背景

DCL 是 DataClawe 项目的一部分。

DataClawe 是一个数据库转换引擎，可将旧版 MySQL 和 PostgreSQL 系统连接到 AI Agent、大模型流水线和云原生服务，无需重写原有系统。

DCL 是让所有人（而不只是数据库工程师）都能实现这种连接的命令语言。

不应摧毁旧版系统，而应对其进行转换。

---

许可证

DCL 规范依据 Creative Commons Attribution 4.0 International (CC BY 4.0) 发布。

您可以自由实现、扩展并基于此规范进行构建。欢迎注明 DataClawe 为出处。

---

DCL v1.1 — 2026 — DataClawe 项目