Run SQL & query tokens
A Comwit database is a Turso/libSQL database you can talk to over SQL. There are two kinds of credential involved: the durable database token you keep in your app’s secret store, and a short-lived query token used for transient, interactive access. This page explains how to run SQL in both places — and why the difference matters.
If you have not created a database yet, start with Create & connect a database.
Run SQL in the web console
Section titled “Run SQL in the web console”The fastest way to poke at your data is the SQL editor in the console:
https://cloud.comwit.io/projects/{projectId}/databases/{databaseId}/queryPick your project and database, type a statement, and run it. No credentials to copy or paste — the console handles auth for you.
Behind the scenes the console does not use your long-lived database token. Instead it mints a short-lived query token scoped to that one database and uses it for the editor session. That keeps your durable connection secret out of the browser entirely.
Run remote SQL with the CLI
Section titled “Run remote SQL with the CLI”Starting with v0.1.6, comwit databases execute runs SQL
remotely through the project-scoped platform API:
comwit databases execute \ --project <project-id> \ --database <database-id> \ --command "select 1 as ok;"Pass a SQLite-compatible SQL file instead of an inline command when you have more than one statement:
comwit databases execute \ --project <project-id> \ --database <database-id> \ --file ./query.sql \ --jsonSupply exactly one of --command or --file. SQL execution is remote by
default; --remote is accepted as a Wrangler-compatible no-op, while --local
is not supported. Without --json, the CLI prints a table and metrics for each
statement. A failed or skipped statement makes the command exit non-zero.
Run remote SQL with the project API
Section titled “Run remote SQL with the project API”Direct API callers use a project-scoped route with a cwt_ token that has the
database:write scope and access to the project:
curl -X POST \ -H "Authorization: Bearer cwt_xxx" \ -H "Content-Type: application/json" \ --data '{"sql":"select 1 as ok;"}' \ https://api.cloud.comwit.io/v1/projects/<project-id>/databases/<database-id>/querySend either one sql value or an ordered batch, never both:
{ "batch": [ { "sql": "insert into notes(body) values ('hello');" }, { "sql": "select id, body from notes order by id;" } ]}The response contains one normalized result for each statement. Successful
results include typed columns and rows plus affected-row, read/write, and
duration metrics. SQL errors are represented as success: false inside the
result envelope even when the HTTP response is 200, so inspect every result.
Statements run in order and later statements are marked skipped after a
failure.
Explicit BEGIN/COMMIT transaction control is allowed, but every request must
finish in autocommit mode. If otherwise-successful SQL leaves a transaction
open, the platform performs a conditional ROLLBACK and returns HTTP 422;
the CLI exits non-zero. If a statement fails while an explicit transaction is
open, cleanup also rolls it back before the request completes.
The request supports at most 250 statements, 50 KiB of UTF-8 SQL per statement, and 900 KiB of SQL in total. The normalized response is limited to 8 MiB. The platform API issues and uses a query token internally; neither the API caller nor the CLI receives that token.
Why query tokens exist
Section titled “Why query tokens exist”Your durable database token is the credential your application uses to connect to
https://db.cloud.comwit.io. It is long-lived and powerful, so it belongs in a
secret store, not in a browser tab.
A browser session is a different trust environment: tokens there can leak through logs, extensions, or shared screens, and a long-lived secret in a browser is hard to revoke cleanly. The query token solves this — it is short-lived and scoped, so an interactive session never has to hold the durable secret. When the token expires, access ends on its own.
How query tokens are issued
Section titled “How query tokens are issued”The console mints a query token for you automatically — there is nothing to call by hand to use the SQL editor above.
During the hybrid-only Database Gateway Phase 1, this server-owned credential may traverse the public Gateway for compatibility. It is not a workload token. Before Comwit-only activation, the Console and Platform API query path moves to the private Louhi SQL origin and keeps the query token entirely on internal service hops.
The underlying route exists in the platform API, but it lives in the
operator-only /v1/databases/* family and is not reachable with a user
cwt_ token (see Running SQL from your own app
below):
API: POST /v1/databases/{database}/query-token (operator token only)
{ "ttl_seconds": 300, "audience": "comwit-cloud-console", "reason": "ad-hoc query"}| Field | Meaning |
|---|---|
ttl_seconds | How long the token stays valid, in seconds. Bounded 1–1800 (max 30 minutes). |
audience | A label describing where the token will be used (for example, sql-console). |
reason | A human-readable note describing why the token was issued. |
Response:
{ "database_id": "db-xxxx", "query_token": "<short-lived token>", "expires_at": "2026-06-16T12:34:56Z", "ttl_seconds": 300, "scope": "..."}Use the returned query_token to run SQL against the data endpoint until
expires_at. Once it expires, request a new one — query tokens are meant to be
cheap and disposable, so prefer minting a fresh, short-lived token over keeping
one around.
Running SQL from your own app
Section titled “Running SQL from your own app”The non-project /v1/databases/* family — including query-token, suspend,
resume, and usage — is operator-token only and rejects user cwt_ tokens
with 403. In other words, you do not issue query tokens yourself from a cwt_
token. For ad-hoc SQL, call the project-scoped POST .../query route above; the
platform API issues the short-lived query token and keeps it server-side.
Durable token rotation and database deletion are also user-facing through the
project-scoped database routes documented in
Manage a database.
To run SQL from your own application, connect with the durable database token
you received at create (or rotate) time, straight to the data endpoint at
https://db.cloud.comwit.io. Keep that token in a secret store — never in a
browser. See Create & connect a database for
how to obtain and use it, and Authentication for how
cwt_ user tokens and scopes work on the rest of the platform API.
Guardrails
Section titled “Guardrails”Some platform-critical databases are protected. Project-scoped SQL execution,
query-token issuance, suspend, resume, delete, token rotation, and restore are
rejected with a 403 against a protected database. This is a launch safety
guard and is not a substitute for your project’s own authorization — see
Manage a database for the full lifecycle.
Related
Section titled “Related”- Create & connect a database — get a durable token and connect your app.
- Manage a database — rotate tokens, suspend, resume, and check usage.
- Authentication — how user tokens work.
Temporary connection refusal
Section titled “Temporary connection refusal”During a Louhi Control replacement, management calls and database gateway
requests can wait up to 30 seconds for a refused TCP connection before reporting
unavailability. An earlier caller deadline or cancellation still wins. Only
refusal before connecting is retried; requests are never replayed after sending
bytes, on EOF/reset/timeout, or on HTTP 502/503. After an ambiguous SQL failure,
check the outcome before any manual retry. The console query route has a
28-second total budget, including query-token issuance, connection recovery, and
SQL execution, to fit inside the hosted runtime
deadline. Budget exhaustion returns a sanitized HTTP 503 busy message with
Retry-After: 1. Hosted apps should allow more than the connection wait plus query
time in their SDK/request deadlines. Longer outages can still fail.
Management admission is bounded across ordinary calls and seed uploads. When
capacity is full, the API returns HTTP 503 with Retry-After: 1 and a fixed busy
message. Wait at least one second before retrying; rejected calls were not sent
to Louhi. Caller cancellation releases admitted calls.
The console query-token endpoint also preserves overload HTTP 503 and
Retry-After, with a busy message so you can retry shortly. Restore requests
rejected by local admission close their creating reservation; ambiguous upstream
failures retain the reservation for recovery.