Serve JSON-RPC

tonic serve --stdio speaks newline-delimited JSON-RPC 2.0 over standard input and output.

Request Shape

{"jsonrpc":"2.0","id":1,"method":"targets.list","params":{}}

Success Shape

{"jsonrpc":"2.0","id":1,"result":{"targets":[]}}

Error Shape

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32000,
    "message": "target \"warehouse\" not found",
    "data": {
      "code": "TONIC_TARGET_NOT_FOUND"
    }
  }
}

Stable service error codes include TONIC_INVALID_PARAMS, TONIC_TARGET_REQUIRED, TONIC_TARGET_NOT_FOUND, TONIC_INVALID_CONTEXT, TONIC_INVALID_SQL, TONIC_SESSION_NOT_FOUND, TONIC_TRANSACTION_REQUIRED, TONIC_PERMISSION_DENIED, TONIC_UNSUPPORTED, TONIC_INVALID_STATEMENT, and TONIC_EXECUTION_ERROR.

Completion

completion.items returns editor-friendly completion items from the persistent inspect cache only. It never opens a target, pings a target, executes SQL, or populates the inspect cache. Cache miss, stale cache rows, malformed cache payloads, and unavailable cache stores return a successful empty result:

{"items":[]}

The request accepts explicit target fallback fields plus query-file metadata:

{
  "text": "-- tonic-file: target=warehouse context.schema=PUBLIC\nselect * from ord",
  "path": "/repo/query.sql",
  "line": 2,
  "column": 18,
  "target": "fallback-target",
  "context": {"database": "ANALYTICS"},
  "autocommit": "on"
}

• text is required and is the source of truth.
• line and column are required 1-based UTF-8 character positions.
• path is optional diagnostic metadata used by query-file directive resolution.
• target, context, and autocommit are optional fallbacks. Query-file directives (tonic-file, tonic-bind, and per-statement tonic) are resolved for the statement at the cursor using the same rules as artifact planning/execution.

The success shape is always:

{
  "items": [
    {
      "label": "orders",
      "kind": "table",
      "type": "table",
      "detail": "PUBLIC.table",
      "description": "Order facts",
      "insertText": "orders"
    }
  ]
}

completion.items may suggest cached catalogs, namespaces, tables, views, and knowable columns from conservative alias-aware table or view sources. For example, cached columns can be returned for common unquoted aliases such as orders o, orders AS o, or JOIN customers c when completing o. or c.<prefix> and the source object resolves to one unambiguous cached table or view. Ambiguous aliases, unresolved objects, unsupported source syntax, stale metadata, malformed cache payloads, and missing column metadata return no column suggestions.

Public completion responses intentionally omit cache diagnostics: success is always { "items": [...] }, including quiet { "items": [] } degradation. Invalid request shapes, missing text, non-positive positions, invalid directives, invalid context overrides, or unresolved targets return structured JSON-RPC errors with the service codes above.

Targets

{"jsonrpc":"2.0","id":1,"method":"targets.list","params":{}}

{
  "targets": [
    {
      "name": "warehouse",
      "backend": "snowflake",
      "context": {
        "database": "ANALYTICS",
        "schema": "PUBLIC",
        "warehouse": "COMPUTE_WH",
        "role": "ANALYST"
      }
    }
  ]
}

targets.ping accepts {"target":"warehouse"} and returns the resolved target summary.

Inline Execution

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "query.executeInline",
  "params": {
    "target": "warehouse",
    "sql": "select 1 as id",
    "context": {"schema": "PUBLIC"},
    "autocommit": "on"
  }
}

Inline execution is request-scoped. The session opens for the request and closes before the response returns.

Artifact Planning And Execution

query.planArtifact parses source text and resolves statement metadata without executing SQL.

query.executeArtifact executes either the whole artifact or one 1-based statement index.

{
  "text": "-- tonic-file: target=warehouse\nselect 1;",
  "path": "/repo/query.sql",
  "target": "fallback-target",
  "context": {"schema": "PUBLIC"},
  "autocommit": "on",
  "statement": 1
}

For service requests, text is the source of truth. path is diagnostic metadata only.

Artifact responses include statements for compatibility and ordered events for report rendering. Event types are:

• print: printable query-file report text from tonic-print directives.
• statement: a planned or executed SQL statement event.

Example shape:

{
  "events": [
    {"type": "print", "line": 1, "text": "# Daily sales report"},
    {"type": "statement", "line": 2, "statement": {}}
  ],
  "statements": []
}

Reusable Sessions

Open a session:

{"target":"warehouse","context":{"schema":"PUBLIC"},"autocommit":"off"}

The result includes a process-local session ID such as sess_1.

Execute one statement on a session:

{"session":"sess_1","sql":"update jobs set touched_at = current_timestamp where id = 1"}

Close a session:

{"session":"sess_1"}

Statement errors do not automatically close a reusable session. Closing a session rolls back any open transaction best-effort.

Inspect Methods

Inspect methods mirror the CLI and all accept refresh where applicable:

• inspect.catalogs
• inspect.namespaces
• inspect.tables
• inspect.views
• inspect.columns
• inspect.viewDefinition
• inspect.ddl

Example:

{
  "target": "warehouse",
  "catalog": "ANALYTICS",
  "namespace": "PUBLIC",
  "includeAll": false,
  "refresh": true
}