Manage a database

Once your database exists, you manage its whole lifecycle through the Comwit Cloud product API: check whether it’s healthy, rotate the connection token, pause it, bring it back, look at usage, or delete it for good. A Comwit database is a Turso/libSQL database (powered by Louhi) that your app connects to at https://db.cloud.comwit.io — but you never run management operations against that data host. Every lifecycle action goes through the product API at https://api.cloud.comwit.io.

If you haven’t created a database yet, start with Create and connect a database. To run queries against one, see Run SQL.

The lifecycle operations

Each operation below acts on one specific database. The table shows the API route, what it does, and which authentication scope it needs.

Action	What it does	API
Get status	Read current health and internals	GET /v1/databases/{database}
Rotate connection token	Issue a fresh one-time token; old one stops working	POST /v1/databases/{database}/token/rotate
Issue query token	Mint a short-lived SQL token	POST /v1/databases/{database}/query-token
Suspend	Pause the database	POST /v1/databases/{database}/suspend
Resume	Bring a suspended database back	POST /v1/databases/{database}/resume
Get usage	Read usage metrics	GET /v1/databases/{database}/usage
Delete	Permanently remove the database	DELETE /v1/databases/{database}

Product surface vs. operator routes

The project-scoped path (the routes under /v1/projects/{projectId}/databases) is the product surface you use for everyday work in the console and CLI. The flat /v1/databases/{database} family shown in the table is operator-token only — those routes back the same lifecycle workflow but are not part of the public, user-token product surface.

Check database status

Read the current state of a database to confirm it’s healthy before you connect or deploy against it.

API

GET /v1/databases/{database}

The status response includes a status field plus low-level libSQL/WAL internals — the runner, the generation, and frame numbers — exposed for inspection. You’ll usually only care about status; the rest is there when you need to debug replication or storage behavior.

Rotate the connection token

Your long-lived database token is the durable secret your app uses to connect. Rotate it when it leaks, when you’ve lost it, or on a routine schedule.

API

POST /v1/databases/{database}/token/rotate

Rotation returns a fresh, one-time database_token in the response.

Rotation is a hard cutover

The moment you rotate, the previous token stops working. Anything still using the old token — running apps, scripts, other developers — loses access until you update it with the new value. Copy the new database_token into your secret store and roll it out before old clients fail.

Comwit never stores raw tenant tokens, so a rotation response is the only time you’ll see the new secret. If you lose it, your only recovery is to rotate again.

Issue a query token

For transient SQL access (for example, an ad-hoc query from a browser session) mint a short-lived query token instead of exposing your durable database token.

API

POST /v1/databases/{database}/query-token

{ "ttl_seconds": 300, "audience": "sql-console", "reason": "ad-hoc query" }

ttl_seconds is bounded between 1 and 3600. The full query-token flow — including the response shape and how the console SQL editor uses it — is covered in Run SQL.

Suspend and resume

Suspend pauses a database; resume brings it back.

Suspend

POST /v1/databases/{database}/suspend

Resume

POST /v1/databases/{database}/resume

Use suspend to temporarily stop a database without losing it, then resume when you need it again.

Inspect usage

Read usage metrics for a database to understand how much it’s being used.

API

GET /v1/databases/{database}/usage

Delete a database

Deleting permanently removes the database.

API

DELETE /v1/databases/{database}

Deletion is permanent

There is no undo. Make sure you have copied out any data you need before you delete.

Guardrails

A few safety rules protect platform-critical databases and your secrets.

Protected tenants

Some databases are critical to the platform itself and are protected by the PLATFORM_API_PROTECTED_TENANTS setting (which by default includes louhi-app and comwit-db-synthetic). Against a protected tenant, the following operations are rejected with 403:

• Suspend
• Resume
• Delete
• Rotate connection token
• Issue query token

This is a launch safety guard to keep critical infrastructure from being paused or torn down by accident. It is not a substitute for project authorization — your request still has to be authorized for the project regardless.

Comwit never stores raw tenant tokens

Comwit does not keep a copy of your raw database token anywhere. The output of create and rotate is the single source of that secret. Treat it accordingly: copy it into your own secret store immediately, and if you lose it, rotate to get a new one.

Tip

The internal PLATFORM_API_SERVER_TOKEN is an operator credential and is never a user token. Your own API tokens are cwt_ tokens — see Authentication.

Related

• Create and connect a database
• Run SQL
• Databases overview
• API errors and idempotency