Branch features: SQL + Python codemode

Coral Codemode

Run a short SQL program or one Monty Python body against Coral data, using explicit read-only execution surfaces for catalog discovery, querying, and result shaping.

SQL example Python example

SQL PR: withcoral/coral#1031
Python PR: withcoral/coral#1192
MCP: optional codemode tools

High level overview

Two codemode runtimes, one Coral data contract

SQL codemode gives agents a single-shot SQL workspace with session-local temporary tables. Python codemode gives agents a bounded Python body with Coral host functions. Both surfaces keep Coral's catalog and query behavior behind explicit CLI and MCP adapters.

SQL

Ordered SQL programs

coral codemode sql runs ordered read-only statements plus CREATE TEMP TABLE ... AS SELECT inside one private query session.

Python

Monty-backed orchestration

coral codemode python runs one Python body through Monty and exposes Coral helpers such as sql() and list_catalog().

Discovery

Catalog-first analysis

Both modes are built for Coral's discovery workflow: inspect schemas, list tables, query catalog tables, and then run the smallest data query that answers the question.

Results

Structured outputs

SQL codemode returns result entries for query statements. Python codemode returns output, captured stdout, and query_count.

Guardrails

Bounded execution

Persistent DDL and DML are rejected in SQL codemode. Python codemode enforces timeout and SQL-call limits, and does not expose filesystem, environment, or network host functions.

MCP gates

Disabled by default

CLI commands are explicit. MCP exposes sql_codemode and codemode only when their corresponding runtime feature flags are enabled.

Why codemode matters

Coral turns data work into programmable analysis

Cloudflare's codemode docs frame code mode as useful when agents need to chain tool calls with logic, compose results, and work with MCP servers that expose many fine-grained operations. Coral has that shape: agents need to discover a catalog, inspect schema constraints, query data, and transform the result before answering.

Context

Catalogs can be wider than the prompt

A source can expose many tables, functions, columns, required filters, and setup inputs. Codemode keeps that surface behind compact discovery and query primitives.

SQL fit

Relational work belongs in SQL

When the task is tabular, SQL codemode lets the agent stage intermediate results in temporary tables and keep joins, filtering, and aggregation close to the query engine.

Python fit

Branching work belongs in code

When the task needs loops, conditionals, fallback behavior, or custom JSON shaping, Python codemode gives the agent a bounded program instead of a brittle sequence of separate calls.

Safety

Execution stays Coral-shaped

Both modes keep authority narrow: read-only data access, feature-gated MCP exposure, explicit CLI invocation, and scoped execution limits.

Examples

Choose SQL for relational plans, Python for orchestration

Both modes are available from the CLI and, when enabled, over MCP. SQL codemode accepts ordered statements; Python codemode accepts one Python body with Coral host functions.

SQL codemode

Run a single-shot SQL program

SQL codemode supports read-only statements and session-local temp tables for multi-step analysis.

coral codemode sql --format json --code '
CREATE TEMP TABLE catalog_sample AS
SELECT schema_name, table_name FROM coral.tables LIMIT 5;
SELECT COUNT(*) AS catalog_total FROM catalog_sample;
SELECT * FROM catalog_sample;
'

{
  "tool": "sql_codemode",
  "arguments": {
    "sql": [
      "CREATE TEMP TABLE catalog_sample AS SELECT schema_name, table_name FROM coral.tables LIMIT 5",
      "SELECT COUNT(*) AS catalog_total FROM catalog_sample",
      "SELECT * FROM catalog_sample"
    ]
  }
}

Python codemode

Run a bounded Python body

Python codemode can call SQL and catalog helpers, then shape the final response as natural JSON.

coral codemode python --format json --code '
catalog = list_catalog(limit=5)
rows = sql("SELECT schema_name, table_name FROM coral.tables LIMIT 5")
{"catalog_total": catalog["total"], "rows": rows}
'

{
  "tool": "codemode",
  "arguments": {
    "code": "catalog = list_catalog(limit=5)\nrows = sql(\"SELECT schema_name, table_name FROM coral.tables LIMIT 5\")\n{\"catalog_total\": catalog[\"total\"], \"rows\": rows}",
    "type_check": true,
    "timeout_ms": 60000,
    "max_sql_calls": 20
  }
}

Result shape

Both modes produce structured data for the agent

SQL codemode emits result entries for query statements and skips temp-table creation entries. Python codemode mirrors the MCP structured result: output, stdout, and query_count.

Execution contract

Two modes, explicit limits

The shared rule is narrow authority. Coral lets agents compose data work without giving them ambient filesystem, environment, network, or persistent mutation powers.

SQL codemode

Surface	Contract
`coral codemode sql`	Explicit CLI command, no feature flag required.
`sql_codemode`	MCP tool exposed only by `sql_codemode`.
Statements	Read-only queries plus session-local temp-table creation.
Mutation	Persistent DDL and DML remain rejected.

Python codemode

Surface	Contract
`coral codemode python`	Explicit CLI command, no feature flag required.
`codemode`	MCP tool exposed only by `codemode`.
Host functions	`sql()`, catalog listing, search, table description, and column listing.
Limits	Default 60 second timeout and 20 SQL calls, capped at 100.

Build

Each codemode has its own implementation track

SQL codemode and Python codemode share the Coral user model, but they are separate pull requests with separate runtime work.

SQL

withcoral/coral#1031

Runtime

Private query session

Executes ordered SQL statements in one private session so temp tables can feed later statements without leaking persistent state.

CLI

`coral codemode sql`

Adds --code, --file, and --format json paths while keeping inline coral sql unchanged and read-only.

MCP

`sql_codemode`

Adds a feature-gated MCP tool enabled by coral features enable sql_codemode or coral --enable-sql-codemode mcp-stdio.

Python

withcoral/coral#1192

Core crate

`coral-codemode`

Runs one Python body through Monty, dispatches Coral host functions, captures output, and serializes the final value as JSON.

CLI

`coral codemode python`

Adds --code, --file, text or JSON output, type-check control, timeout, and SQL call limits.

MCP

`codemode`

Adds a feature-gated MCP tool with a structured output schema and the same execution behavior as the CLI adapter.