Create & connect a database

A Comwit Cloud database is a Turso/libSQL database (powered by Louhi) that lives inside one of your projects. You create and manage it through the product API or the comwit CLI, and your app talks to it directly as a plain libSQL endpoint at https://db.cloud.comwit.io.

This page walks you through creating a database, safely handling the connection token, listing the databases in a project, and pointing your app at the new database.

Before you start

You need a project to put the database in. Every database belongs to a project, and most commands take a --project <projectId> (or {projectId} in the API). If you have not installed the CLI yet, see Install the CLI.

Create a database

Pick a --name for the database (for example app-db). With the CLI:

comwit CLI

comwit databases create --project <projectId> --name app-db

The equivalent API call is a POST to the project’s databases collection:

API

POST /v1/projects/{projectId}/databases

Request body

{ "name": "app-db" }

A successful create returns the new database and, importantly, a one-time connection token:

Response

{
  "database_id": "db-xxxx",
  "database_url": "https://db.cloud.comwit.io/v1/<tenant_id>",
  "created": true,
  "database_token": "<one-time token>"
}

The fields are:

• database_id — the stable identifier for this database (for example db-xxxx). Use it in lifecycle and SQL operations.
• database_url — the libSQL data endpoint your app connects to (see Connect your app below).
• created — true when the database was provisioned by this request.
• database_token — the long-lived connection token your app authenticates with.

Copy the token now — it is shown only once

The connection token is returned exactly once

database_token is returned once, at create time. Comwit Cloud never stores raw tenant tokens, so it cannot show it to you again later. Copy it straight into your app’s secret store now.

If you lose it, you can’t look it up — you have to rotate the token to get a fresh one. See Manage a database for rotation.

Tip

Keep the token out of source control and out of the browser. For ad-hoc SQL in the console you don’t need this durable token at all — Comwit issues short-lived query tokens for that. See Run SQL.

List the databases in a project

To see what already exists in a project:

comwit CLI

comwit databases list --project <projectId>

API

GET /v1/projects/{projectId}/databases

The response wraps the databases in a databases array:

Response

{
  "databases": [
    {
      "database_id": "db-xxxx",
      "name": "app-db",
      "status": "...",
      "created_at": "2026-06-16T12:34:56Z",
      "database_url": "https://db.cloud.comwit.io/v1/<tenant_id>"
    }
  ]
}

Each entry includes database_id, name, status, created_at, and database_url (omitted when empty). Note that the list does not include any token — tokens only ever come back from create and rotate.

Connect your app

Your database is a standard libSQL endpoint, so any libSQL client can connect to it using the URL plus the token. The URL has this shape:

Database URL

https://db.cloud.comwit.io/v1/<tenant_id>

Use database_url (from create or list) as the connection URL and the database_token (from create or rotate) as the auth token in your libSQL client. Store both as secrets/environment variables in your app.

db.cloud.comwit.io is a data endpoint only

db.cloud.comwit.io serves database traffic and nothing else. Management, docs, and debug paths are blocked on the public listener. Every lifecycle operation — create, rotate, suspend, resume, delete — goes through the product API (api.cloud.comwit.io) or the CLI, never the data host.

Next steps

• Run SQL against your new database from the console or with a query token.
• Manage a database to rotate the token, check status and usage, or delete it.
• Deploy an app and wire it to this database.