Repository navigation
Troubleshooting
sqld is not running or the URL is wrong. For local development:
docker run --name libsql-test-sqld -p 8081:8080 ghcr.io/tursodatabase/libsql-server:latestThen use DB_URL=http://127.0.0.1:8081 and a token (see
Configuration).
- The test suite seeds itself at bootstrap — you don't need to do anything
special (
composer install && ./vendor/bin/pest). - With
TURSO_HTTP_SKIP_SEED=1, or in your own app, the database is whatever you pointDB_URLat — the package does not create tables automatically. - In Laravel, make sure your migrations ran; this package is only the client, not a migration runner.
- The token expired (Turso Cloud tokens are JWTs — check
exp). - The URL points at the wrong database (
libsql://<db>-<org>.turso.io). - A local-only test token is being used against Turso Cloud (or vice versa) — those are different authorities.
- The library throws
LibSQLErrorwith the server's message for these — if you are catching nothing, the exception text tells you which case it was.
GET /version exists only on self-hosted libsql-server (sqld). Against
Turso Cloud, LibSQL::version() throws a catchable LibSQLError
(HTTP 404: route not found: ["version"]). To check live connectivity from
cloud, use the pipeline:
$v = $db->query('SELECT sqlite_version() AS v')->fetchArray(
\Darkterminal\TursoHttp\LibSQL::LIBSQL_ASSOC
)[0]['v'];php artisan package:discover
php artisan optimize:clearIf you published the config earlier with different keys, republish with
--tag=turso-http-config and re-check config/turso-http.php.
CI provisions a seeded sqld service container and the suite seeds itself —
if you see this, your DB_URL is pointing somewhere other than the service
container (e.g. host.docker.internal from inside the same host), or
TURSO_HTTP_SKIP_SEED=1 leaked into the environment.
Only exact Y-m-d H:i:s strings convert, and only when DB_TIMEZONE
resolves to a known timezone. Otherwise the value is returned as stored.
The client creates a fresh curl handle per HTTP request (no connection
pooling). It is safe to create multiple LibSQL instances, but in hot paths
prefer one shared instance per process (e.g. Laravel's turso singleton) so
you don't pay DSN parsing and object setup per query.