Reference

​

Installing

Install the package to your project using composer:

composer require turso/libsql

​

Initializing

Make sure to add use Libsql\Database to access the Database object.

$db = new Database("local.db")

​

In-Memory Databases

libSQL supports connecting to in-memory databases for cases where you don’t require persistence:

$db = new Database(":memory:");

Or the simpler:

$db = new Database();

​

Local Development

You can work locally by passing a path as the first parameter.

$db = new Database("local.db")

Or more explicitly:

$db = new Database(path: "local.db")

​

Remote Only

You can use a remote only database by passing url and authToken.

$db = new Database(
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
);

​

Embedded Replicas

You can work with embedded replicas by passing a path, url and authToken. Embedded replicas can sync from the remote URL and delegate writes to the remote primary database:

$db = new Database(
    path: 'test.db',
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
);

​

Sync Interval

The sync_interval function allows you to set an interval for automatic synchronization of the database in the background:

$db = new Database(
    path: 'test.db',
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
    syncInterval: 300, // Sync every 3 seconds
);

​

Manual Sync

The sync function allows you to sync manually the local database with the remote counterpart:

$db->sync()

​

Read Your Own Writes

The readYourWrites parameter configures the database connection to ensure that writes are immediately visible to subsequent read operations initiated by the same connection. This is enabled by default, and is particularly important in distributed systems to ensure consistency from the perspective of the writing process.

You can disable this behavior by passing false:

$db = new Database(
    path: 'test.db',
    url: getenv('TURSO_URL'),
    authToken: getenv('TURSO_AUTH_TOKEN'),
    readYourWrites: false,
);

​

Simple Query

You can acquire a connection from a database and call query() to invoke a SQL statement, as well as optional arguments:

​

Prepared Statements

You can prepare a cached statement using prepare(), bind parameters, and then query it:

$stmt = $conn->prepare("SELECT * FROM users where id = ?");
$rows = $stmt->bind([1])->query();

​

Placeholders

libSQL supports the use of positional and named placeholders within SQL statements:

​

Batch Transactions

A batch consists of multiple SQL statements executed sequentially within an implicit transaction. The backend handles the transaction: success commits all changes, while any failure results in a full rollback with no modifications.

$conn->execute_batch("
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL
  );

  INSERT INTO users (name) VALUES ('Alice');
  INSERT INTO users (name) VALUES ('Bob');
");

​

Interactive Transactions

Interactive transactions in SQLite ensure the consistency of a series of read and write operations within a transaction’s scope. These transactions give you control over when to commit or roll back changes, isolating them from other client activity.

$tx = conn->transaction();

$tx->execute("INSERT INTO users (name) VALUES (?1)", ["Iku"]);
$tx->execute("INSERT INTO users (name) VALUES (?1)", ["Iku 2"]);

tx->commit(); // or, $tx->rollback()