{
  "markdown": "# DCL — DataClawe Command Language\n\n**A JSON-based database command standard for AI agents, frontend engineers, and anyone who finds SQL too complex.**\n\n> \"If you understand MySQL and MSX-BASIC, you already understand DCL.\"\n\n---\n\n## What is DCL?\n\nDCL (DataClawe Command Language) is an open standard for communicating with databases using simple JSON.\n\nIt is designed for:\n\n- **AI agents** (Claude, GPT, Cursor, and others) to safely read and write structured data\n- **Frontend engineers** who need database access without writing SQL\n- **MCP (Model Context Protocol)** tool integration\n- **Any application** connecting to MySQL or PostgreSQL — legacy or new\n\nDCL translates into native SQL internally. Your existing database does not change. Your existing application does not change.\n\n---\n\n## Design Philosophy\n\nDCL follows three rules:\n\n**1. If you can read it, you understand it.**\nNo cryptic operators. No framework-specific syntax. No `:` chaining.\n\n**2. MySQL words. JSON structure.**\nActions like `SELECT`, `INSERT`, `UPDATE`, `DELETE` are exactly what you expect. WHERE conditions are written the way MySQL engineers already write them.\n\n**3. MSX-BASIC level simplicity.**\nIf a condition like `age >= 20` needs an explanation, the design has failed.\n\n**4. Simple by default. Powerful when needed.**\nStandard covers most real-world needs. Advanced covers the rest. You never pay the complexity cost until you need it.\n\n---\n\n## Quick Start\n\n### Fetch data\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"SELECT\",\n  \"table\": \"users\",\n  \"columns\": [\"id\", \"name\", \"email\"],\n  \"where\": [\n    \"status = 'active'\",\n    \"age >= 20\"\n  ],\n  \"order\": \"created_at DESC\",\n  \"limit\": 10,\n  \"offset\": 0\n}\n```\n\n### Insert a record\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"INSERT\",\n  \"table\": \"users\",\n  \"data\": {\n    \"name\": \"kimura\",\n    \"email\": \"kimura@example.com\",\n    \"status\": \"active\"\n  }\n}\n```\n\n### Update records\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"UPDATE\",\n  \"table\": \"users\",\n  \"data\": {\n    \"status\": \"inactive\"\n  },\n  \"where\": [\n    \"id = 123\"\n  ]\n}\n```\n\n### Delete a record (logical delete)\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"DELETE\",\n  \"table\": \"users\",\n  \"where\": [\n    \"id = 123\"\n  ]\n}\n```\n\n---\n\n## Actions\n\n| Action | Description | Read-only |\n|--------|-------------|-----------|\n| `SELECT` | Fetch one or more records | ✅ |\n| `COUNT` | Count matching records | ✅ |\n| `EXISTS` | Check if a record exists | ✅ |\n| `SCHEMA` | Get column definitions for a table | ✅ |\n| `TABLES` | List all available tables | ✅ |\n| `STATS` | Get record count, last updated, and storage size | ✅ |\n| `TIMELINE` | Get chronological change history of a record | ✅ |\n| `INSERT` | Create a new record | ❌ |\n| `UPDATE` | Update existing records | ❌ |\n| `DELETE` | Logical delete (status flag) | ❌ |\n| `TABLE_CREATE` | Create a new table (empty declaration) | ❌ |\n| `TABLE_COPY` | Copy a table | ❌ |\n| `TABLE_RENAME` | Rename a table | ❌ |\n| `TABLE_DROP` | Logical delete a table | ❌ |\n\n---\n\n## WHERE Conditions\n\nWHERE is an array of condition strings. Multiple conditions are AND by default.\n\n### Basic comparisons\n\n```json\n\"where\": [\n  \"status = 'active'\",\n  \"age >= 20\",\n  \"age <= 60\",\n  \"status != 'deleted'\"\n]\n```\n\n### OR conditions\n\n```json\n\"where\": {\n  \"OR\": [\n    \"status = 'active'\",\n    \"status = 'pending'\"\n  ]\n}\n```\n\n### AND + OR combined\n\n```json\n\"where\": {\n  \"AND\": [\n    \"age >= 20\",\n    {\n      \"OR\": [\n        \"status = 'active'\",\n        \"status = 'pending'\"\n      ]\n    }\n  ]\n}\n```\n\n### LIKE\n\n```json\n\"where\": [\n  \"name LIKE 'kimura%'\"\n]\n```\n\n### IN\n\n```json\n\"where\": [\n  \"status IN ('active', 'pending')\"\n]\n```\n\n### BETWEEN\n\n```json\n\"where\": [\n  \"age BETWEEN 20 AND 60\"\n]\n```\n\n### NULL checks\n\n```json\n\"where\": [\n  \"deleted_at IS NULL\"\n]\n```\n\n```json\n\"where\": [\n  \"deleted_at IS NOT NULL\"\n]\n```\n\n---\n\n## Aggregation\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"SELECT\",\n  \"table\": \"orders\",\n  \"columns\": [\n    \"SUM(amount) AS total\",\n    \"AVG(amount) AS average\",\n    \"COUNT(*) AS count\"\n  ],\n  \"where\": [\n    \"status = 'paid'\"\n  ],\n  \"group\": \"customer_id\"\n}\n```\n\n---\n\n## COUNT\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"COUNT\",\n  \"table\": \"users\",\n  \"where\": [\n    \"status = 'active'\"\n  ]\n}\n```\n\n---\n\n## EXISTS\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"EXISTS\",\n  \"table\": \"users\",\n  \"where\": [\n    \"email = 'kimura@example.com'\"\n  ]\n}\n```\n\n---\n\n## SCHEMA\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"SCHEMA\",\n  \"table\": \"users\"\n}\n```\n\n---\n\n## TABLES\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"TABLES\"\n}\n```\n\n---\n\n## TABLE_CREATE — Create a table\n\nDeclares a new empty table. Internally creates a single `status=8` schema declaration row.\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"TABLE_CREATE\",\n  \"table\": \"users\"\n}\n```\n\nWith optional schema definition:\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"TABLE_CREATE\",\n  \"table\": \"users\",\n  \"schema\": {\n    \"name\":  \"text\",\n    \"age\":   \"integer\",\n    \"email\": \"text\"\n  }\n}\n```\n\n> **Without schema:** Created with `schema: null`. Column types are auto-registered as `text` on first INSERT.\n\n---\n\n## status=8 Schema Declaration Row\n\nDataClawe maintains one `status=8` declaration row per table.\n\n| status value | Purpose |\n|---|---|\n| `status=1` | Normal record (active) |\n| `status=8` | Table declaration + schema cache |\n| `status=9` | Logically deleted |\n\n**Example status=8 row content:**\n\n```json\n{\n  \"schema\": {\n    \"name\":  \"text\",\n    \"age\":   \"text\",\n    \"email\": \"text\"\n  }\n}\n```\n\n**Auto Schema Evolution:**\n\nWriting to a non-existent table via INSERT auto-creates the status=8 row.\nNew columns are automatically appended to the status=8 schema on each INSERT (type defaults to `text`).\n\n```\nFirst INSERT: {\"name\": \"kimura\", \"age\": 25}\n  → Auto-create status=8: {\"name\":\"text\", \"age\":\"text\"}\n  → INSERT the record\n\nSecond INSERT: {\"name\": \"suzuki\", \"phone\": \"090-xxxx\"}\n  → \"phone\" is new → auto-append to status=8 schema\n  → schema: {\"name\":\"text\", \"age\":\"text\", \"phone\":\"text\"}\n```\n\nWhen connecting to legacy MySQL/PostgreSQL, actual column types (`VARCHAR(255)`, `INT`, etc.) are recorded in the status=8 row.\n\n---\n\n## STATS — Table statistics\n\nReturns record count, last updated timestamp, and storage size. Useful for AI agents to assess table state before operating.\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"STATS\",\n  \"table\": \"users\"\n}\n```\n\nExample response:\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"status\": \"OK\",\n  \"data\": {\n    \"table\": \"users\",\n    \"record_count\": 1024,\n    \"last_updated\": \"2026-03-28T10:00:00Z\",\n    \"size_kb\": 512\n  }\n}\n```\n\n---\n\n## TIMELINE — Record change history\n\nReturns the change history (created, updated, logical delete) of a record in chronological order. Useful for AI agents tracking data evolution.\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"TIMELINE\",\n  \"table\": \"users\",\n  \"where\": [\n    \"id = 123\"\n  ]\n}\n```\n\n---\n\n## TABLE_COPY — Copy a table\n\nCopies a table under a new name. Used for backups, migrations, and testing.\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"TABLE_COPY\",\n  \"table\": \"users\",\n  \"target_table\": \"users_backup_20260328\"\n}\n```\n\n---\n\n## TABLE_RENAME — Rename a table\n\nRenames a table.\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"TABLE_RENAME\",\n  \"table\": \"users_old\",\n  \"new_name\": \"users_archived\"\n}\n```\n\n---\n\n## TABLE_DROP — Drop a table (logical delete)\n\nLogically deletes a table. Data is not physically removed immediately.\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"TABLE_DROP\",\n  \"table\": \"users_temp\"\n}\n```\n\n> **Note:** TABLE_DROP is a logical delete — not equivalent to SQL `DROP TABLE`. Data is not immediately destroyed.\n\n---\n\n## Response Format\n\n### Success\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"status\": \"OK\",\n  \"count\": 42,\n  \"data\": [\n    { \"id\": 1, \"name\": \"kimura\", \"email\": \"kimura@example.com\" }\n  ],\n  \"meta\": {\n    \"table\": \"users\",\n    \"elapsed_ms\": 12\n  }\n}\n```\n\n### Error\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"status\": \"ERROR\",\n  \"code\": \"TABLE_NOT_FOUND\",\n  \"message\": \"Table 'users' does not exist\"\n}\n```\n\n### Error codes\n\n| Code | Description |\n|------|-------------|\n| `TABLE_NOT_FOUND` | Specified table does not exist |\n| `COLUMN_NOT_FOUND` | Specified column does not exist |\n| `INVALID_ACTION` | Unknown action specified |\n| `INVALID_WHERE` | WHERE condition could not be parsed |\n| `PERMISSION_DENIED` | Tenant does not have access |\n| `CONNECTION_ERROR` | Database connection failed |\n\n---\n\n## Integration\n\nDCL works over two protocols. The DCL command itself is identical in both cases.\n\n| Protocol | Used by | Guide |\n|----------|---------|-------|\n| REST API (HTTPS POST) | Frontend, Backend, any HTTP client | See [README.api.md](README.api.md) |\n| MCP (JSON-RPC 2.0 / SSE) | AI agents (Claude, GPT, Cursor) | See [README.mcp.md](README.mcp.md) |\n\n### DCL payload (identical in both protocols)\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"SELECT\",\n  \"table\": \"orders\",\n  \"where\": [\n    \"status = 'pending'\",\n    \"created_at >= '2026-01-01'\"\n  ],\n  \"order\": \"created_at DESC\",\n  \"limit\": 100\n}\n```\n\nThis DCL JSON is the same regardless of whether you call via REST API or MCP. Only the outer protocol layer differs.\n\n---\n\n## Supported Databases\n\n| Database | Status |\n|----------|--------|\n| MySQL 5.x / 8.x | ✅ Supported |\n| PostgreSQL 9–18 | ✅ Supported |\n| Others | 📋 Planned |\n\nDCL normalizes differences between MySQL and PostgreSQL. You write one DCL command. DataClawe handles the rest.\n\n---\n\n## Complexity Layers\n\nDCL is designed in two layers. You choose the layer you need.\n\n---\n\n### DCL Standard — this specification\n\nFor AI agents, frontend engineers, and anyone doing straightforward data operations.\n\n- No JOIN. No subquery.\n- Readable by anyone who knows MySQL basics.\n- Covers the vast majority of real-world CRUD needs.\n\nIf Standard covers your needs, you never have to go further.\n\n---\n\n### DCL Advanced — coming in v1.1\n\nFor backend engineers who need more expressive power.\n\nSame JSON structure. Same DataClawe engine. More capability when you need it.\n\n**JOIN**\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"SELECT\",\n  \"table\": \"users\",\n  \"columns\": [\"users.id\", \"users.name\", \"orders.amount\"],\n  \"join\": [\n    {\n      \"table\": \"orders\",\n      \"on\": \"users.id = orders.user_id\",\n      \"type\": \"LEFT\"\n    }\n  ],\n  \"where\": [\n    \"users.status = 'active'\"\n  ],\n  \"order\": \"orders.amount DESC\",\n  \"limit\": 20\n}\n```\n\n**Subquery**\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"SELECT\",\n  \"table\": \"users\",\n  \"where\": [\n    \"id IN (SELECT user_id FROM orders WHERE status = 'paid')\"\n  ]\n}\n```\n\n**Multiple JOINs**\n\n```json\n{\n  \"dcl\": \"1.0\",\n  \"action\": \"SELECT\",\n  \"table\": \"orders\",\n  \"columns\": [\n    \"orders.id\",\n    \"users.name AS customer\",\n    \"products.name AS product\",\n    \"orders.amount\"\n  ],\n  \"join\": [\n    {\n      \"table\": \"users\",\n      \"on\": \"orders.user_id = users.id\",\n      \"type\": \"INNER\"\n    },\n    {\n      \"table\": \"products\",\n      \"on\": \"orders.product_id = products.id\",\n      \"type\": \"LEFT\"\n    }\n  ],\n  \"where\": [\n    \"orders.status = 'paid'\",\n    \"orders.created_at >= '2026-01-01'\"\n  ],\n  \"order\": \"orders.created_at DESC\"\n}\n```\n\n**JOIN types supported in Advanced**\n\n| Type | Description |\n|------|-------------|\n| `INNER` | Records matching in both tables |\n| `LEFT` | All left, matching right |\n| `RIGHT` | All right, matching left |\n\n---\n\n### Why two layers?\n\n```\nSQL solved everything in one spec.\nThat is why SQL is still hard after 30 years.\n\nDCL Standard is for everyone.\nDCL Advanced is for when you need more.\nYou always start simple. You go deeper only when you must.\n```\n\nThe same engine handles both. The same JSON structure. No new syntax to learn when you move from Standard to Advanced — just new keys.\n\n---\n\n### What remains intentionally unsupported\n\nThe following are out of scope in both Standard and Advanced, to keep DCL safe and predictable for AI agents:\n\n- Stored procedures\n- Schema creation or `ALTER TABLE`\n- Raw SQL passthrough\n- Physical schema destruction (immediate `DROP TABLE` equivalent)\n\n> **Note:** `TABLE_DROP` in DCL is a **logical delete** — distinct from SQL `DROP TABLE`. It does not immediately destroy data.\n\nDCL is a data operation language, not a schema management language.\n\n---\n\n## Versioning\n\nThe `\"dcl\": \"1.0\"` field is required in every request and response.\n\nFuture versions will remain backward compatible. A DCL 1.0 request will always work against a DCL 2.0 server.\n\n---\n\n## Contributing\n\nDCL is an open specification. Feedback, proposals, and pull requests are welcome.\n\n- Open an issue to propose a new action or operator\n- Open a pull request to improve documentation or examples\n- All contributions must follow the design philosophy: **readable, MySQL-familiar, BASIC-level simplicity**\n\n---\n\n## Roadmap\n\n**v1.0 — DCL Standard**\n- [ ] Spec finalization\n- [ ] JSON Schema for validation (`dcl.schema.json`)\n- [ ] Reference implementation in Go (DataClawe Engine)\n- [ ] MCP server reference implementation\n- [ ] MySQL wire protocol support\n- [ ] Multi-tenant isolation specification\n\n**v1.1 — DCL Advanced**\n- [ ] JOIN specification (INNER / LEFT / RIGHT)\n- [ ] Subquery support\n- [ ] Nested aggregation\n\n**SDKs**\n- [ ] JavaScript / TypeScript\n- [ ] PHP\n- [ ] Python\n- [ ] Go\n\n---\n\n## Pricing\n\nDataClawe uses a tiered pricing model that scales from individual developers to enterprise.\n\n**Initial registration fee: $20 (one-time, all plans)**\n\n| Plan | Monthly | Records | Sessions | SLA |\n|------|---------|---------|----------|-----|\n| **Free** | $0 | 2,000 | 100/day | No |\n| **Personal** | $20 | up to 20,000 | up to 20,000/month | No |\n| **Business** | $20+ | Unlimited | Unlimited | No |\n| **Enterprise** | Contact us | Unlimited | Unlimited | Yes |\n\n**Usage rates (Business plan — overage)**\n\n| Item | Unit price |\n|------|-----------|\n| Record storage | $0.001 / record / month |\n| Session | $0.001 / session |\n\n**Record size limit: 100KB per record.**\nThis covers IoT sensor data, CRM contacts, medical text records, WordPress posts, and financial transactions.\nImages and video files are out of scope — store them in CDN/object storage and keep the URL in DataClawe.\n\nFor Enterprise pricing, contact us at [dataclawe.com/enterprise](https://dataclawe.com/enterprise).\n\n---\n\n## Background\n\nDCL is developed as part of the [DataClawe](https://dataclawe.com) project.\n\nDataClawe is a database translation engine that connects legacy MySQL and PostgreSQL systems to AI agents, LLM pipelines, and cloud-native services — without rewriting the original system.\n\nDCL is the command language that makes this connection possible for everyone, not just database engineers.\n\n> Legacy systems should not be destroyed. They should be translated.\n\n---\n\n## License\n\nDCL specification is released under [Creative Commons Attribution 4.0 International (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/).\n\nYou are free to implement, extend, and build upon this specification. Attribution to DataClawe is appreciated.\n\n---\n\n*DCL v1.1 — 2026 — DataClawe Project*\n",
  "bytes": 14838,
  "sha": "c56f85ade2613cdf7b0c32f5318c07807a4412fecfd4be7c1a524cdd6d13b5de",
  "repo_slug": "dataclawe/dcl-spec",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_dataclawe_dataclawe_mcp_f0250118/readme"
}