Manage a database
Once your database exists, you manage its public lifecycle through the Comwit
Cloud product API: list project databases, rotate the connection token, and
delete databases you own. 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
Section titled “The lifecycle operations”Each public operation below is project-scoped and works with a cwt_ token whose
scopes and project membership allow it.
| Action | What it does | API |
|---|---|---|
| List project databases | Read ids, names, status, and URLs | GET /v1/projects/{projectId}/databases |
| Create database | Provision a project database and return a one-time token | POST /v1/projects/{projectId}/databases |
| Rotate connection token | Issue a fresh one-time token; old one stops working | POST /v1/projects/{projectId}/databases/{databaseId}/token/rotate |
| Delete | Permanently remove the database | DELETE /v1/projects/{projectId}/databases/{databaseId} |
Check database status
Section titled “Check database status”List the project databases to see each database’s current status and data URL.
comwit databases list --project <projectId>GET /v1/projects/{projectId}/databasesDetailed Louhi runner/WAL internals live behind the operator-only status route and are not required for normal app setup.
The old non-project POST /v1/databases create route is retired. It remains as
a deprecated 410 Gone compatibility tombstone and never provisions a
database; use POST /v1/projects/{projectId}/databases for every create.
Rotate the connection token
Section titled “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.
POST /v1/projects/{projectId}/databases/{databaseId}/token/rotatecomwit databases token rotate --project <projectId> --database <databaseId>Rotation returns a fresh, one-time database_token in the response.
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
Section titled “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.
POST /v1/databases/{database}/query-tokenThis route is operator-only today. The web console mints query tokens on your
behalf for the SQL editor; a cwt_ user token should not call this route
directly.
{ "ttl_seconds": 300, "audience": "sql-console", "reason": "ad-hoc query" }ttl_seconds is bounded between 1 and 1800 (30 minutes). 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
Section titled “Suspend and resume”Suspend pauses a database; resume brings it back. These routes are operator-only
today and are not exposed through the public comwit CLI.
POST /v1/databases/{database}/suspendPOST /v1/databases/{database}/resumeOperators use these routes to temporarily stop a database without deleting it, then bring it back when needed.
Inspect usage
Section titled “Inspect usage”Read usage metrics for a database to understand how much it’s being used. Usage inspection is operator-only today.
GET /v1/databases/{database}/usageDelete a database
Section titled “Delete a database”Deleting permanently removes the database.
DELETE /v1/projects/{projectId}/databases/{databaseId}comwit databases delete --project <projectId> --database <databaseId>After the pending Database Gateway lifecycle rollout, deletion first records
the database as deleting, then removes the Louhi tenant and idempotently
finalizes the project record. If a request is interrupted, retry the same
delete: it resumes cleanup and can finalize even when the tenant is already
absent.
Guardrails
Section titled “Guardrails”A few safety rules protect platform-critical databases and your secrets.
Protected tenants
Section titled “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
Section titled “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.