Skip to content

Configuration

darkterminal edited this page Nov 11, 2026 · 1 revision

Configuration

Plain PHP — DSN

Native-extension-compatible DSN syntax:

use Darkterminal\TursoHttp\LibSQL;

$db = new LibSQL("dbname=libsql://<db>-<org>.turso.io&authToken=<token>");

The DSN is dbname=<url>&authToken=<token> (parameter name kept for compatibility with the native client).

Plain PHP — environment variable fallbacks

When the global helpers (useDB(), useQueryBuilder(), …) are used, the connection details are read from the environment:

Variable Purpose Default
DB_URL or TURSO_URL libSQL HTTP endpoint http://127.0.0.1:8081
DB_TOKEN or TURSO_TOKEN auth token public local-test fixture (see below)
DB_STRICT_QUERY 'true' enables strict-query (EXPLAIN) mode in the query builder false
DB_TIMEZONE target timezone for DATETIME columns UTC

Defaults are intended for local development against a seeded libsql-server. The default token only works against the local, empty libsql-server and is a public test fixture — never use it against anything else. In any real deployment set both DB_URL and DB_TOKEN explicitly.

Laravel

The package ships an auto-discovered service provider and a facade — no manual registration is needed. Configuration resolves from DB_URL / TURSO_URL and DB_TOKEN / TURSO_TOKEN:

php artisan vendor:publish --provider="Darkterminal\TursoHttp\Laravel\TursoServiceProvider" --tag=turso-http-config

Published config (config/turso-http.php):

return [
    'url' => env('DB_URL', env('TURSO_URL', 'http://127.0.0.1:8081')),
    'token' => env('DB_TOKEN', env('TURSO_TOKEN', '')),
    'options' => [],   // optional: closures, e.g. before_hook / after_hook
];

The turso singleton shares one LibSQL instance with the facade (Turso::…) and with LibSQL::class (autowired). See Laravel Integration.

DATETIME columns and timezones

DATETIME values stored as Y-m-d H:i:s are converted from UTC to DB_TIMEZONE on read, but only when the value matches that exact format and DB_TIMEZONE resolves to a known timezone for this package. Arbitrary DATETIME strings are returned unchanged. Storage is always UTC as written by the app. (Code-verified; no dedicated test covers every edge format.)

To disable timezone conversion, leave DB_TIMEZONE=UTC.

Clone this wiki locally