This package provides a Turso database driver for Laravel, allowing you to use Turso as your database backend in Laravel applications. The driver communicates with the Turso database server using an HTTP client.

You can find a demo application that uses this Turso database driver in the richan-fongdasen/pingcrm repository.

• PHP 8.2 or higher
• Laravel 11.0 or higher
• Node.js 16 or higher

You can install the package via Composer:

composer require richan-fongdasen/turso-laravel

To use Turso as your database driver in Laravel, append the following configuration to the connections array in your config/database.php file:

'turso' => [
    'driver'                  => 'turso',
    'db_url'                  => env('DB_URL', 'http://localhost:8080'),
    'access_token'            => env('DB_ACCESS_TOKEN'),
    'db_replica'              => env('DB_REPLICA'),
    'database'                => null, // Leave this null
    'prefix'                  => env('DB_PREFIX', ''),
    'foreign_key_constraints' => env('DB_FOREIGN_KEYS', true),
    'sticky'                  => env('DB_STICKY', true),
],

Publish the configuration file and sync script by running the following command:

php artisan vendor:publish --provider="RichanFongdasen\Turso\TursoLaravelServiceProvider"

The above command publishes the following files:

• config/turso-laravel.php
• turso-sync.mjs

The content of the config/turso-laravel.php file should look like this:

return [
    'client' => [
        'connect_timeout' => env('TURSO_CONNECT_TIMEOUT', 2),
        'timeout'         => env('TURSO_REQUEST_TIMEOUT', 5),
    ],

    'sync_command' => [
        'node_path'       => env('NODE_PATH'), // Full path to the node executable. E.g: /usr/bin/node
        'script_filename' => 'turso-sync.mjs',
        'script_path'     => realpath(__DIR__ . '/..'),
        'timeout'         => 60,
    ],
];

You may need to set the NODE_PATH environment variable to the path of your Node.js executable. This is required to run the sync script.

The Turso database driver requires Node.js to run the sync script. Install the Node.js dependencies by running the following command:

npm install @libsql/client

In Laravel applications, the database driver configuration is stored in your .env file. Here are the available configurations for the Turso database driver:

DB_CONNECTION=turso
DB_URL=http://localhost:8080
DB_ACCESS_TOKEN=
DB_REPLICA=
DB_PREFIX=
DB_FOREIGN_KEYS=true
DB_STICKY=true

For local development, you can use the local Turso database server provided by the Turso team. Refer to the Turso CLI documentation for instructions on running the local Turso database server.

The Turso database driver should work as expected with Laravel's Query Builder and Eloquent ORM. Here are some examples:

use App\Models\User;
use Illuminate\Support\Facades\DB;

// Using Query Builder
$users = DB::table('users')->orderBy('name')->get();

// Using Eloquent ORM
$users = User::with('posts')->orderBy('name')->get();

The driver supports the embedded replica feature. If you're unfamiliar with this feature, refer to the Turso embedded replica article for more information.

Run the sync script manually using the following Artisan command:

php artisan turso:sync

You may encounter an error if the path to the replica database does not exist. This is expected when the replica database has not been created yet.

Run the sync script programmatically using the following code:

use Illuminate\Support\Facades\DB;
use RichanFongdasen\Turso\Facades\Turso;

if ( DB::hasModifiedRecords() ) {
    // Run the sync script immediately
    Turso::sync();

    // Run the sync script in the background
    Turso::backgroundSync();
}

To debug the HTTP requests and responses sent and received by the Turso database client, enable the debugging feature as follows:

Turso::enableQueryLog();

DB::table('users')->get();

// Get the query log
$logs = Turso::getQueryLog();

Please see CHANGELOG for more information on what has changed recently.

Please see CONTRIBUTING for details.

Please review our security policy on how to report security vulnerabilities.

• Richan Fongdasen
• All Contributors

The MIT License (MIT). Please see License File for more information.