Skip to content

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.

Each public operation below is project-scoped and works with a cwt_ token whose scopes and project membership allow it.

ActionWhat it doesAPI
List project databasesRead ids, names, status, and URLsGET /v1/projects/{projectId}/databases
Create databaseProvision a project database and return a one-time tokenPOST /v1/projects/{projectId}/databases
Rotate connection tokenIssue a fresh one-time token; old one stops workingPOST /v1/projects/{projectId}/databases/{databaseId}/token/rotate
DeletePermanently remove the databaseDELETE /v1/projects/{projectId}/databases/{databaseId}

List the project databases to see each database’s current status and data URL.

CLI
comwit databases list --project <projectId>
API
GET /v1/projects/{projectId}/databases

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

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/projects/{projectId}/databases/{databaseId}/token/rotate
CLI
comwit 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.

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

This 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 pauses a database; resume brings it back. These routes are operator-only today and are not exposed through the public comwit CLI.

Suspend
POST /v1/databases/{database}/suspend
Resume
POST /v1/databases/{database}/resume

Operators use these routes to temporarily stop a database without deleting it, then bring it back when needed.

Read usage metrics for a database to understand how much it’s being used. Usage inspection is operator-only today.

API
GET /v1/databases/{database}/usage

Deleting permanently removes the database.

API
DELETE /v1/projects/{projectId}/databases/{databaseId}
CLI
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.

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

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