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

The fastest way to poke at your data is the SQL editor in the console:

https://cloud.comwit.io/projects/{projectId}/databases/{databaseId}/query

Pick 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.

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

The console mints a query token for you automatically — there is nothing to call by hand to use the SQL editor above.

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–3600 (max 1 hour).
`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

The non-project /v1/databases/* family — including query-token, token/rotate, 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; the console does it for you.

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

Some platform-critical databases are protected. Issuing a query token (along with suspend, resume, delete, and token rotation) against a protected database is rejected with a 403. 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.

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.