DataClawe — Database as a Utility

DCL — DataClawe Command Language

A JSON-based database command standard for AI agents, frontend engineers, and anyone who finds SQL too complex.

"If you understand MySQL and MSX-BASIC, you already understand DCL."

---

What is DCL?

DCL (DataClawe Command Language) is an open standard for communicating with databases using simple JSON.

It is designed for:

• AI agents (Claude, GPT, Cursor, and others) to safely read and write structured data
• Frontend engineers who need database access without writing SQL
• MCP (Model Context Protocol) tool integration
• Any application connecting to MySQL or PostgreSQL — legacy or new

DCL translates into native SQL internally. Your existing database does not change. Your existing application does not change.

---

Design Philosophy

DCL follows three rules:

1. If you can read it, you understand it. No cryptic operators. No framework-specific syntax. No : chaining.

2. MySQL words. JSON structure. Actions like SELECT, INSERT, UPDATE, DELETE are exactly what you expect. WHERE conditions are written the way MySQL engineers already write them.

3. MSX-BASIC level simplicity. If a condition like age >= 20 needs an explanation, the design has failed.

4. Simple by default. Powerful when needed. Standard covers most real-world needs. Advanced covers the rest. You never pay the complexity cost until you need it.

---

Quick Start

Fetch data

{

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

Insert a record

{

"dcl": "1.0", "action": "INSERT", "table": "users", "data": { "name": "kimura", "email": "kimura@example.com", "status": "active" } }

Update records

{

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

Delete a record (logical delete)

{

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

---

Actions

---

WHERE Conditions

WHERE is an array of condition strings. Multiple conditions are AND by default.

Basic comparisons

"where": [

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

OR conditions

"where": {

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

AND + OR combined

"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 checks

"where": [

"deleted_at IS NULL" ]

"where": [

"deleted_at IS NOT NULL" ]

---

Aggregation

{

"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 = 'kimura@example.com'" ] }

---

SCHEMA

{

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

---

TABLES

{

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

---

TABLE_CREATE — Create a table

Declares a new empty table. Internally creates a single status=8 schema declaration row.

{

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

With optional schema definition:

{

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

Without schema: Created with schema: null. Column types are auto-registered as text on first INSERT.

---

status=8 Schema Declaration Row

DataClawe maintains one status=8 declaration row per table.

Example status=8 row content:

{

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

Auto Schema Evolution:

Writing to a non-existent table via INSERT auto-creates the status=8 row. New columns are automatically appended to the status=8 schema on each INSERT (type defaults to 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"}

When connecting to legacy MySQL/PostgreSQL, actual column types (VARCHAR(255), INT, etc.) are recorded in the status=8 row.

---

STATS — Table statistics

Returns record count, last updated timestamp, and storage size. Useful for AI agents to assess table state before operating.

{

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

Example response:

{

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

---

TIMELINE — Record change history

Returns the change history (created, updated, logical delete) of a record in chronological order. Useful for AI agents tracking data evolution.

{

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

---

TABLE_COPY — Copy a table

Copies a table under a new name. Used for backups, migrations, and testing.

{

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

---

TABLE_RENAME — Rename a table

Renames a table.

{

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

---

TABLE_DROP — Drop a table (logical delete)

Logically deletes a table. Data is not physically removed immediately.

{

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

Note: TABLE_DROP is a logical delete — not equivalent to SQL DROP TABLE. Data is not immediately destroyed.

---

Response Format

Success

{

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

Error

{

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

Error codes

---

Integration

DCL works over two protocols. The DCL command itself is identical in both cases.

DCL payload (identical in both protocols)

{

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

This DCL JSON is the same regardless of whether you call via REST API or MCP. Only the outer protocol layer differs.

---

Supported Databases

DCL normalizes differences between MySQL and PostgreSQL. You write one DCL command. DataClawe handles the rest.

---

Complexity Layers

DCL is designed in two layers. You choose the layer you need.

---

DCL Standard — this specification

For AI agents, frontend engineers, and anyone doing straightforward data operations.

• No JOIN. No subquery.
• Readable by anyone who knows MySQL basics.
• Covers the vast majority of real-world CRUD needs.

If Standard covers your needs, you never have to go further.

---

DCL Advanced — coming in v1.1

For backend engineers who need more expressive power.

Same JSON structure. Same DataClawe engine. More capability when you need it.

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 }

Subquery

{

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

Multiple JOINs

{

"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" }

JOIN types supported in Advanced

---

Why two layers?

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.

The same engine handles both. The same JSON structure. No new syntax to learn when you move from Standard to Advanced — just new keys.

---

What remains intentionally unsupported

The following are out of scope in both Standard and Advanced, to keep DCL safe and predictable for AI agents:

• Stored procedures
• Schema creation or ALTER TABLE
• Raw SQL passthrough
• Physical schema destruction (immediate DROP TABLE equivalent)

Note: TABLE_DROP in DCL is a logical delete — distinct from SQL DROP TABLE. It does not immediately destroy data.

DCL is a data operation lan