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
Section titled “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
Section titled “Create a database”Pick a --name for the database (for example app-db). With the CLI:
comwit databases create --project <projectId> --name app-dbThe equivalent API call is a POST to the project’s databases collection:
POST /v1/projects/{projectId}/databases{ "name": "app-db" }A successful create returns the new database and, importantly, a one-time connection token:
{ "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 exampledb-xxxx). Use it in lifecycle and SQL operations.database_url— the libSQL data endpoint your app connects to (see Connect your app below).created—truewhen 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”Create a database from a SQLite file
Section titled “Create a database from a SQLite file”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.
comwit databases create \ --project <projectId> \ --name app-db \ --from-file ./app.sqlite \ --token-out ./app-db.tokenThe 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:
comwit databases create \ --project <projectId> \ --name app-db \ --from-dump ./d1-dump.sql \ --token-out ./app-db.tokenThe 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/-shmsidecar. From a WAL-mode source, runsqlite3 src.db ".backup out.sqlite". PRAGMA integrity_checkmust beokandPRAGMA foreign_key_checkmust 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-filedoes not accept a.sqldump; use--from-dumporimport-dumpbelow.
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.
Import an existing SQL dump
Section titled “Import an existing SQL dump”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:
comwit databases import-dump \ --project <projectId> \ --name app-db \ --from-dump dump.sqlThe command prints the new database, url, and one-time token. Use url as
DATABASE_URL and token as DATABASE_AUTH_TOKEN.
Common dump commands:
wrangler d1 export <DB_NAME> --remote --output d1-dump.sqlsqlite3 source.db .dump > sqlite-dump.sqlturso db shell <database-name> .dump > turso-dump.sqlThis 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.
List the databases in a project
Section titled “List the databases in a project”To see what already exists in a project:
comwit databases list --project <projectId>GET /v1/projects/{projectId}/databasesThe response wraps the databases in a databases array:
{ "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
Section titled “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:
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:
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.
Next steps
Section titled “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.