tursodatabase/turso-driver-laravel
| Install | |
|---|---|
composer require tursodatabase/turso-driver-laravel |
|
| Latest Version: | 1.7.0 |
| PHP: | ^8.2 |
| Laravel: | 10 – 13 |
| Older releases: | 4 – 9 |
| License: | MIT |
| Last Updated: | Nov 10, 2026 |
| Links: | GitHub · Packagist |
[!IMPORTANT] Offline writes are currently in beta and come in two flavors: the journaled flavor for Turso Cloud (
DB_OFFLINE_WRITES=truealone) and the sqld flavor for self-hosted libsql-server (DB_SQLD_OFFLINE_MODE=trueandDB_OFFLINE_WRITES=true). Both are supported via the libSQL PHP extension v1.7.0+ (see Offline Writes in the Wiki).
SQLite for Production. Powered by libSQL and the libSQL PHP extension.
libSQL is an open-contribution fork of SQLite. This package provides a
Laravel database driver built on the native libSQL PHP extension; Eloquent,
the Query Builder, migrations and transactions are exercised by the test
suite and the docker/proof/ integration harness.
Requirements
| Component | Requirement |
|---|---|
| PHP | 8.2, 8.3, 8.4 or 8.5 |
| Laravel | 12 or 13 (13 requires PHP 8.3+) |
| libSQL PHP extension | installed automatically via Artisan (see below) |
| Turso PHP installer | 2.2+ (bundled) |
Installation
composer require tursodatabase/turso-driver-laravel
Register the service provider in bootstrap/providers.php:
return [
App\Providers\AppServiceProvider::class,
Turso\Driver\Laravel\LibSQLDriverServiceProvider::class, // add this line
];
Install the libSQL PHP extension (bundled with this package):
php artisan turso-php:install
The installer also provides turso-php:update and turso-php:uninstall, plus
environment, token, certificate and sqld-server management commands — see
src/Commands/ for the implementations, or php artisan | grep turso-php
for the full list.
Configuration
The driver reads its settings from .env:
DB_CONNECTION=libsql
DB_DATABASE=database.sqlite # or :memory:
DB_AUTH_TOKEN=<your-database-auth-token-from-turso>
DB_SYNC_URL=<your-database-url-from-turso>
DB_SYNC_INTERVAL=5
DB_READ_YOUR_WRITES=true
DB_ENCRYPTION_KEY=<your-encryption-key>
DB_SQLD_OFFLINE_MODE=false
DB_OFFLINE_WRITES=false
And the connections block of config/database.php:
'libsql' => [
'driver' => 'libsql',
'database' => env('DB_DATABASE', database_path('database.sqlite')),
'prefix' => '',
'url' => env('DB_SYNC_URL', ''),
'authToken' => env('DB_AUTH_TOKEN', ''),
'syncInterval' => env('DB_SYNC_INTERVAL', 5),
'read_your_writes' => env('DB_READ_YOUR_WRITES', true),
'encryptionKey' => env('DB_ENCRYPTION_KEY', ''),
'sqldOfflineMode' => env('DB_SQLD_OFFLINE_MODE', false),
'offlineWrites' => env('DB_OFFLINE_WRITES', false),
],
All options, defaults and their meaning are documented on the Wiki · Configuration.
Connection types
libSQL supports four connection types — in-memory, local, remote, and remote replica (embedded replica). Examples and verified setups are on the Wiki · Connection Types.
Usage
Database operations use the standard Illuminate\Support\Facades\DB
interface. When connected via remote replica (embedded replica), the driver
adds a DB::sync() method for triggering a manual replica sync.
Write failures throw since v1.4.0 — wrap writes in try/catch as you would with the SQLite driver:
try {
DB::table('users')->insert(['name' => 'Budi Dalton', 'email' => 'budi.dalton@duck.com']);
} catch (\Illuminate\Database\QueryException $e) {
report($e);
}
Query Builder, Eloquent (relations, casts, soft deletes, collections),
migrations, transactions, the schema builder, vector types and encryption at
rest are all covered by the Pest suite and the docker/proof/ harness.
For the full tour — Eloquent examples, vector index syntax, offline-write
bootstrap, DB::sync() semantics and more — see
the Wiki · Basic Usage.
Offline-write modes
Two opt-in flavors (both need libSQL Extension ≥ 1.7.0):
| Env variable | Value | Flavor |
|---|---|---|
DB_OFFLINE_WRITES |
true |
Turso Cloud (beta) — remote_replica mode, DB::sync() pushes to the cloud |
DB_SQLD_OFFLINE_MODE + DB_OFFLINE_WRITES |
both true |
Self-hosted sqld — offline_write mode, journal replay via DB::sync() |
The Turso Cloud flavor bootstraps from the cloud on first sync — see Wiki · Offline Writes for the required ordering and verified output.
Documentation
The full user manual & tutorial lives on the Wiki:
- Installation
- Configuration
- Connection Types
- Basic Usage
- Offline Writes (two flavors)
- Verification & Proof Harness
- Known Limitations
- Troubleshooting
Testing
composer install
./vendor/bin/pest
Server-dependent tests are skipped by default; they run in CI against a
seeded libsql-server. See Wiki · Verification.
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Security Vulnerabilities
Please review our security policy on how to report security vulnerabilities.
Contributors
License
Licensed under the MIT License. See LICENSE.md for details.
Related Packages
Powerful PHP database abstraction layer (DBAL) with many features for database s...
Laravel Serializable Closure provides an easy and secure way to serialize closur...
Version History
| Version | Released | PHP | Laravel | License |
|---|---|---|---|---|
| 1.7.0 | ^8.2 | MIT | ||
| 1.6.0 | ^8.2 | MIT | ||
| 1.5.0 | ^8.2 | MIT | ||
| 1.4.0 | ^8.2 | MIT | ||
| 1.3.2 | ^8.2 | MIT | ||
| 1.3.1 | ^8.2 | MIT | ||
| 1.3.0 | ^8.2 | MIT | ||
| 1.2.10 | ^8.2 | MIT | ||
| 1.2.9 | ^8.2 | MIT | ||
| 1.2.8 | ^8.2 | MIT | ||
| 1.2.7 | ^8.2 | MIT | ||
| 1.2.6 | ^8.2 | ^11.44|| | MIT | |
| 1.2.5 | ^8.2 | * | MIT | |
| 1.2.4 | ^8.2 | * | MIT | |
| 1.2.3 | ^8.2 | ^10.0|| | MIT | |
| 1.2.2 | ^8.2 | ^10.0|| | MIT | |
| 1.2.1 | ^8.2 | ^10.0|| | MIT | |
| 1.2.0 | ^8.2 | ^10.0|| | MIT | |
| 1.1.1 | ^8.2 | ^10.0|| | MIT | |
| 1.1.0 | ^8.2 | ^10.0|| | MIT | |
| 1.0.14 | ^8.2 | ^10.0|| | MIT | |
| 1.0.13 | ^8.2 | ^10.0|| | MIT | |
| 1.0.12 | ^8.2 | ^10.0|| | MIT | |
| 1.0.11 | ^8.2 | ^10.0|| | MIT | |
| 1.0.9 | ^8.2 | ^10.0|| | MIT | |
| 1.0.7 | ^8.2 | ^10.0|| | MIT | |
| 1.0.6 | ^8.2 | ^10.0|| | MIT | |
| 1.0.5 | ^8.2 | ^10.0|| | MIT | |
| 1.0.4 | ^8.2 | ^10.0|| | MIT | |
| 1.0.3 | ^8.2 | ^10.0|| | MIT |
Showing the latest 30 of 31. See every release on Packagist