Kernlift
Database

Use Turso

Run the app on a Turso libSQL database through the SQLite schema branch and the turso adapter.

Turso serves libSQL, which is compatible with SQLite. The app keeps the SQLite schema and the SQLite migration chain and uses a different client. DATABASE_DIALECT stays sqlite, and you set DATABASE_ADAPTER=turso.

Before you begin

  • A Turso database with its URL and a token: turso db show --url <name> and turso db tokens create <name>.
  • @libsql/client, already a dependency of this project. The database layer require.resolves it and only loads it when the turso adapter is selected, so a SQLite or Postgres deployment does not load it.
  • Nothing in the admin console. The database connection is one of the three things that stay in the environment. See Configuration model.

Create the database in Turso

Install and log in to the CLI using the Turso CLI guide, then run turso db create <database-name>. Copy the libsql:// URL from turso db show --url <database-name> and create an application token with turso db tokens create <database-name>. Enter those values as DATABASE_URL and DATABASE_AUTH_TOKEN below. The CLI login credential is not the application database token. Keep the token server-side and set both values in the deployment environment as well. See Turso tokens.

Connect the database

Set the connection

.env
DATABASE_DIALECT=sqlite
DATABASE_ADAPTER=turso
DATABASE_URL=libsql://YOUR-DATABASE.turso.io
DATABASE_AUTH_TOKEN=YOUR-TURSO-TOKEN

The adapter fails at startup if either value is missing. It does not fall back to a local file, so a misconfigured deployment cannot write to the wrong database.

Build the schema

pnpm db:migrate

This applies drizzle/migrations/sqlite, the same chain a local SQLite file and a Cloudflare D1 database get. Turso needs no migrations of its own.

Create the administrator

SUPER_ADMIN_EMAIL=you@example.com SUPER_ADMIN_PASSWORD='<password>' pnpm db:bootstrap-super-admin

This also seeds the roles, permissions and the default rate-limit rules. You can re-run it. It inserts what is missing and does not overwrite what an operator has edited.

How the adapter is selected

DATABASE_DIALECT=sqlite selects the SQLite schema and migrations. DATABASE_ADAPTER=turso selects the libSQL client. The adapter fails at startup without a libsql:// address, token or installed @libsql/client package. See Environment variables for the exact startup fields.

The built-in sqlite, postgres, d1 and turso adapters are registered through the same registerDatabaseAdapter function used by custom adapters.

Verify

pnpm validate:db-adapters

Then start the app, sign in as the administrator and open /admin. Run two more checks once:

  1. Unset DATABASE_AUTH_TOKEN and start. It throws DATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=turso and does not open a local file.
  2. Write something from the console, for example grant a licence, then read the row with the Turso CLI. The CLI shows the row the app wrote.

Troubleshooting

DATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=turso

Create a token with turso db tokens create <name> and set it.

DATABASE_URL is required when DATABASE_ADAPTER=turso

Set DATABASE_URL to the libsql:// URL from turso db show --url <name>.

The adapter is not selected at all

canHandle also requires @libsql/client to resolve. After a fresh clone, run pnpm install.

Reference

Next steps