README.md

Caution

There is a new adapter coming soon for Laravel that doesn't require using an extension. This extension doesn't support offline writes beta. Join us on Discord to talk more - https://discord.gg/turso

SQLite for Production. Powered by libSQL and libSQL Extension for PHP.

LibSQL is a fork of SQLite and this package is #1 LibSQL Driver that run natively using LibSQL Native Extension/Driver/Whatever and support Laravel Ecosystem.

---

Installation

You can install the package via composer:

composer require tursodatabase/turso-driver-laravel

Then register the service provider at bootstrap/providers.php array:

return [
    App\Providers\AppServiceProvider::class,
    Turso\Driver\Laravel\LibSQLDriverServiceProvider::class, // Here
];

The package now include the turso-php-installer, so you can install the LibSQL Extension via artisan command:

php artisan turso-php:install

And you can read the all command using php artisan | grep turso-php or read the manual

Laravel Sail

Don't worry, we also provide Laravel Sail step by step guide for you read: Sailing with LibSQL

Environment Variable Overview

You need to know the additional configuration in .env file, which come from Laravel and which come from LibSQL Driver. And here is the overview of .env:

Laravel

DB_CONNECTION=libsql
DB_DATABASE=database.sqlite

• DB_CONNECTION key is represent default database connection like libsql, sqlite, mysql, mariadb, pgsql, and sqlsrv.
• DB_DATABASE key is represent the location of database name or in this case is database filename.

LibSQL Driver

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=
DB_REMOTE_ONLY=false

Create a new Turso Database here

Here’s the information in a nicely formatted markdown section for a README:

---

Environment Variables for Turso Driver

Below is a list of environment variables used to configure the Turso driver. Each variable plays a role in defining database connection and behavior:

• DB_AUTH_TOKEN
  You can generate this token using the following command:

  turso db tokens create <database-name>

  Alternatively, visit your Turso Dashboard, select the desired database, and generate the token from there.

• DB_SYNC_URL
  This URL is automatically generated by Turso when you create a new database. Retrieve the database URL using the command:

  turso db show --url <database-name>

• DB_SYNC_INTERVAL
  This variable defines the interval (in seconds) at which an embedded replica synchronizes with the primary database. It ensures automatic synchronization of the database in the background.
  Default: 5 seconds
  Use case: Keeps replicas up-to-date with minimal manual intervention.

• DB_READ_YOUR_WRITES
  Ensures that writes made by a connection are immediately visible to subsequent reads from the same connection. This is vital for maintaining consistency in distributed systems.
  Default: true
  Use case: Guarantees clients always see their latest writes.

• DB_ENCRYPTION_KEY
  Specifies the encryption key used for database encryption. This key is critical for securing data at rest, ensuring only authorized individuals can decrypt the database content.
  Default: Empty
  Use case: Protects sensitive data stored on disk.

• DB_REMOTE_ONLY
  Determines if only the remote database should be used for read and write operations.
  Default: false
  Use case: Set to true to strictly use a remote connection without local synchronization.

Choose Your Connection Needs

LibSQL has 4 types of connections to interact with the database: In-Memory Connection, Local Connection, Remote Connection, and Remote Replica Connection (Embedded Replica)

💾 — In-Memory Connection

To be able to use LibSQL in-memory as if you were using SQLite, simply change the following .env:

DB_CONNECTION=libsql
DB_DATABASE=:memory:
  

🖥 — Local Connection

To be able to use LibSQL locally as if you were using SQLite, simply change the following .env:

DB_CONNECTION=libsql
DB_DATABASE=database.sqlite
  

Ignore other LibSQL .env variables.

🌏 — Remote Connection

To use LibSQL Remote Connection only, you can define the following .env variables:

DB_CONNECTION=libsql
DB_AUTH_TOKEN=<your-database-auth-token-from-turso>
DB_SYNC_URL=<your-database-url-from-turso>
DB_REMOTE_ONLY=true
  

🌱 — Remote Replica Connection (Embedded Replica)

To configure remote replica connection (embedded replica), you can simply use the following .env:

DB_CONNECTION=libsql
DB_DATABASE=database.sqlite
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=
DB_REMOTE_ONLY=false
  

That's it! How easy to make different connection using LibSQL Driver in Laravel, right?!

Database Configuration

Add this configuration at config/database.php inside the connections array:

'libsql' => [
    'driver' => 'libsql',
    'url' => env('DB_DATABASE', database_path('database.sqlite')),
    'authToken' => env('DB_AUTH_TOKEN', ''),
    'syncUrl' => env('DB_SYNC_URL', ''),
    'syncInterval' => env('DB_SYNC_INTERVAL', 5),
    'read_your_writes' => env('DB_READ_YOUR_WRITES', true),
    'encryptionKey' => env('DB_ENCRYPTION_KEY', ''),
    'remoteOnly' => env('DB_REMOTE_ONLY', false),
    'database' => null,
    'prefix' => '',
],

Copy and Paste and do not change it! Or try to change it and will broke your app or give you malfunction.

Usage

For database operation usage, everything have same interface like usual when you using Illuminate\Support\Facades\DB in your database model. But remember, this is LibSQL they have sync method that can be used when you connect with Remote Replica Connection (Embedded Replica).

use Illuminate\Support\Facades\DB;

// Create
DB::table('users')->insert([
    'name' => 'Budi Dalton',
    'email' => '[email protected]'
]);

// Read
DB::table('users')->get();
DB::table('users')->where('id', 2)->first();
DB::table('users')->orderBy('id', 'DESC')->limit(2)->get();

// Update
DB::table('users')->where('id', 2)->update(['name' => 'Doni Mandala']);

// Delete
DB::table('users')->where('id', 2)->delete();

// Transaction
try {
    DB::beginTransaction();

    $updated = DB::table('users')->where('id', 9)->update(['name' => 'Doni Kumala']);

    if ($updated) {
        echo "It's updated";
        DB::commit();
    } else {
        echo "Not updated";
        DB::rollBack();
    }

    $data = DB::table('users')->orderBy('id', 'DESC')->limit(2)->get();
    dump($data);
} catch (\Exception $e) {
    DB::rollBack();
    echo "An error occurred: " . $e->getMessage();
}

// Sync
DB::sync();

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

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