Skip to content

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.

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.

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

Section titled “Copy the token now — it is shown only once”

If your data is already a single SQLite file, upload it and Comwit builds the new database from it server-side. This is much faster than replaying a SQL dump for anything beyond a few megabytes.

Create a database from a SQLite file
comwit databases create \
--project <projectId> \
--name app-db \
--from-file ./app.sqlite \
--token-out ./app-db.token

The CLI checks the file locally, streams it with a progress indicator, waits until the database is ready, and prints the database_id, database_url, and one-time token.

Have a SQL dump instead of a SQLite file? Let the CLI convert it for you:

Create a database from a SQL dump
comwit databases create \
--project <projectId> \
--name app-db \
--from-dump ./d1-dump.sql \
--token-out ./app-db.token

The dump is replayed into a temporary single-file SQLite database locally (no sqlite3 install needed) and then uploaded exactly like --from-file. Add --sqlite-out ./app.sqlite to keep the converted file.

Before you upload:

  • Use a single file with no -wal/-shm sidecar. From a WAL-mode source, run sqlite3 src.db ".backup out.sqlite".
  • PRAGMA integrity_check must be ok and PRAGMA foreign_key_check must return nothing. The CLI runs both for you first.
  • Generated columns and extension-backed virtual tables are not supported.
  • Size: 100 bytes to 2 GiB. --from-file does not accept a .sql dump; use --from-dump or import-dump below.

The platform-to-Louhi upload must finish within 280 seconds, including streaming and the response; a shorter caller deadline wins. Large or slow uploads can exceed this limit even below 2 GiB. Use a faster connection or an upload source closer to the service. Uploads have no range resume and are not automatically replayed: after a timeout, check the operation first, poll if it is queued or later, and re-upload from byte zero only while awaiting_upload.

Seed upload deadline expiry (including the inbound body read deadline) returns 504 with code SEED_UPLOAD_TIMEOUT. The sanitized message states the 280-second upload limit and instructs callers to check the operation status before any manual retry; re-upload from byte zero only while awaiting_upload.

This creates a new database only. It never overwrites an existing one.

If you already have data in D1, SQLite, or Turso, export a SQL dump and let the CLI create a fresh Louhi database from it:

Create a database from a dump
comwit databases import-dump \
--project <projectId> \
--name app-db \
--from-dump dump.sql

The command prints the new database, url, and one-time token. Use url as DATABASE_URL and token as DATABASE_AUTH_TOKEN.

Common dump commands:

Dump sources
wrangler d1 export <DB_NAME> --remote --output d1-dump.sql
sqlite3 source.db .dump > sqlite-dump.sql
turso db shell <database-name> .dump > turso-dump.sql

This is SQL dump only and new database only. For a raw SQLite .db file use comwit databases create --from-file above instead of dumping. If import fails, the CLI deletes only the database it just created unless you pass --keep-failed-db.

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.

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. During the current hybrid compatibility period, the one-time database_token from create or rotate remains an accepted auth token.

After Database Gateway rollout, deployed workloads should instead use a project-owned cwp_ token granted only database:connect. A human owner/admin/member cwt_ with that scope may connect, but a read-only viewer cwt_ is denied even if it carries the scope because a libSQL connection can execute arbitrary SQL.

Phase 1 of the Gateway rollout remains Hybrid for every create and restore. The one-time legacy token therefore remains available while workloads migrate to cwp_; Comwit-only creation and one-way legacy disable are activated only after the public route and direct-origin closure are proved.

For the currently deployed hybrid path, the CLI can set app environment values with the one-time legacy token:

Set app env
comwit apps env set --project <projectId> --app <appId> DATABASE_URL https://db.cloud.comwit.io/v1/<tenant_id>/
comwit apps env set --project <projectId> --app <appId> DATABASE_AUTH_TOKEN <database_token>

After Database Gateway rollout, replace the legacy token with a project-owned cwp_ carrying only database:connect.

An older cwt_ or cwp_ does not acquire database:connect automatically. Create a replacement token with that scope instead of reusing a credential issued before the Gateway contract existed.

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