Skip to content

Known Limitations

Imam Ali Mustofa edited this page Nov 11, 2026 · 2 revisions

Known Limitations

HTTP-only

This client speaks Hrana over HTTP. It does not:

  • link against the native libSQL PHP extension (there is no .so here),
  • do embedded replicas or native sync,
  • work offline in any mode.

For the native extension, see turso-driver-laravel / turso-doctrine-dbal (they are separate packages).

No offline / journaled writes

The "offline writes" flavors of libsql-server / Turso Cloud require native sync semantics (.sync(), local WAL drain). A plain HTTP client cannot participate, so these modes are unsupported and untested — use the native extension instead.

Live Turso Cloud vs sqld — /version

The GET /version route exists only on a self-hosted libsql-server (sqld 0.24.33 …). Turso Cloud returns HTTP 404 (route not found) for the same call — LibSQL::version() therefore throws a catchable LibSQLError against Turso Cloud. Use the pipeline (SELECT sqlite_version()) for portable connectivity checks. This package's own test suite proves cloud connectivity via the latter.

HTTP errors and failures

Any non-2xx response (401 / 403 / 404, …) throws Darkterminal\TursoHttp\core\LibSQLError with the server's error message when present (e.g. HTTP 404: route not found: ["version"]). Server-side pipeline errors (e.g. no such table: …, returned with HTTP 200) also throw the same exception. There is no die() / exit() in the library; catch what you need. Errors are never silently returned as data. (Earlier releases in the 2.x line died with an echo — upgrading is recommended.)

DATETIME handling

Values that are not exactly Y-m-d H:i:s are returned as stored. Only exact matches are converted UTC → DB_TIMEZONE (when DB_TIMEZONE resolves to a timezone known to this package).

Full-fetch results only

LibSQLResult is read fully into memory. There is no streaming cursor API. For very large result sets, paginate in SQL (LIMIT/OFFSET).

Hrana v2 and v3

Both are supported and normalized in one code path; the client does not negotiate protocol version — it accepts what the server sends. If a future server emits new typed-cell kinds, LibSQLTypes::decode() falls back to passsing the raw cell through unchanged (yours to handle).

PHP requirement

^8.3 — older PHP versions are not supported.

Clone this wiki locally