Connection Types

Connection Types

Four connection modes. All four are exercised by the test suite and/or the docker/proof/ harness.

In-Memory

DB_CONNECTION=libsql
DB_DATABASE=:memory:

Classic SQLite behaviour in memory. Used by most feature tests (tests/Feature/* against :memory:).

Local (database file)

DB_CONNECTION=libsql
DB_DATABASE=database.sqlite

No auth token or sync URL needed. tests/Feature/LocalRemoteReplicaTest.php and the embedded replica flow in docker/proof/ both write to a local file.

Remote (Turso Cloud)

DB_CONNECTION=libsql
DB_AUTH_TOKEN=<token>
DB_SYNC_URL=<url>

No local file — traffic goes over HTTPS to Turso Cloud. Verified live against a real Turso Cloud database (query round-trip + probe tables cleaned up).

Remote Replica (embedded replica)

DB_CONNECTION=libsql
DB_DATABASE=database.sqlite
DB_AUTH_TOKEN=<token>
DB_SYNC_URL=<url>
DB_SYNC_INTERVAL=5
DB_READ_YOUR_WRITES=true

Reads hit the local file; writes go through the replica which syncs with the primary. DB::sync() triggers a manual sync.

Verified by:

• tests/Feature/LocalRemoteReplicaTest.php (in CI against seeded sqld on 8082),
• docker/proof/ (replica phases: bootstrap pull, local journaled writes, sync() drain, second-client read-back).

Notes

• libsql URLs use the libsql://… scheme. Plain http://… URLs into tursodatabase are not accepted by this driver (Laravel treats http:// as an unknown driver).
• Remote connections require the database URL; plain http://127.0.0.1:8080 to a self-hosted sqld works only when paired with DB_SQLD_OFFLINE_MODE / offline-write configuration.