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>andturso db tokens create <name>. @libsql/client, already a dependency of this project. The database layerrequire.resolves it and only loads it when thetursoadapter 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
DATABASE_DIALECT=sqlite
DATABASE_ADAPTER=turso
DATABASE_URL=libsql://YOUR-DATABASE.turso.io
DATABASE_AUTH_TOKEN=YOUR-TURSO-TOKENThe 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:migrateThis 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-adminThis 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-adaptersThen start the app, sign in as the administrator and open /admin. Run two more checks
once:
- Unset
DATABASE_AUTH_TOKENand start. It throwsDATABASE_AUTH_TOKEN is required when DATABASE_ADAPTER=tursoand does not open a local file. - 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.