Why Turso and why SQLite:

Turso is an open-source, SQLite-compatible database written in Rust. This module is used to connect directly to Turso Cloud — they have a generous 5GB free tier. Although this module will get you started very quickly, the real advantage to this architecture is to leverage a local SQLite database that syncs to Turso Cloud. To be clear, this driver is only for connectivity to their cloud database. But later, you could run SQLite locally that syncs with the cloud. You would connect to that local database with an HTTP API endpoint. Then you would only pay for syncs making database costs extremely cheap for any website!

bx-libsql

A minimal BoxLang module that wraps DBeaver's LibSQL JDBC driver so it can be used as a registered BoxLang datasource driver (driver: "libsql") for connecting to Turso Cloud / libSQL databases.

Why this exists

BoxLang's this.datasources supports a class:-based shorthand for arbitrary JDBC drivers, but that path does not reliably wire the driver into BoxLang's underlying HikariCP connection pool — it fails with:

Unable to create datasource connection to URL [...] : Failed to get driver instance for jdbcUrl=...

This happens even when the driver class and its dependencies load and instantiate correctly on their own (confirmed via direct Java interop). BoxLang's DatasourceService only correctly wires up a driver when it's registered as a proper module (box.json + ModuleConfig.bx), each with its own classloader — not from a raw jar referenced via this.javaSettings.loadPaths or dropped into a lib folder. This module exists purely to satisfy that requirement for a driver (com.dbeaver.jdbc.driver.libsql.LibSqlDriver) that has no official BoxLang module yet.

What's inside libs/

• com.dbeaver.jdbc.driver.libsql-1.0.8.jar — the actual JDBC driver (dbeaver/dbeaver-jdbc-libsql)
• com.dbeaver.jdbc.api-2.8.0.jar — required compile dependency
• org.jkiss.utils-2.8.0.jar — required compile dependency
• gson-2.14.0.jar — required compile dependency (JSON handling)

The driver jar alone is not sufficient — Maven Central only publishes it as a thin jar; these three dependency jars must be present alongside it.

Usage

In Application.cfc:

this.datasources = {
    tursoDB = {
        driver: "libsql",
        class: "com.dbeaver.jdbc.driver.libsql.LibSqlDriver",
        connectionString: getSystemSetting("TURSO_CONNECTIONSTRING", ""),
        username: "", // Leave empty for token-based auth
        password: getSystemSetting("TURSO_AUTH_TOKEN", "")
    }
};

TURSO_CONNECTIONSTRING and TURSO_AUTH_TOKEN are read from .env (never commit real values to Application.cfc directly).

Connection string format: jdbc:dbeaver: libsql:https: //<your-turso-db>.turso.io (no spaces in string)

Location

This module lives at the project level (boxlang_modules/bx-libsql/), which BoxLang picks up automatically alongside its server-level modules/ directory — no server config changes needed. This keeps it version-controlled with the rest of the project rather than living only in CommandBox's per-server cache.

Upgrading the driver

To update to a newer dbeaver-jdbc-libsql version, download the new driver jar plus whatever com.dbeaver.jdbc.api / org.jkiss.utils / gson versions its own pom.xml declares as compile dependencies (check the jar's embedded META-INF/maven/.../pom.xml), and replace the jars in libs/ accordingly.

Issues:

I used Claude Code to figure all this out for me. If you have issues, I recommend you do the same