Skip to content

Basic Usage

darkterminal edited this page Nov 11, 2026 · 1 revision

Basic Usage

All examples below were executed against a local sqld (output shown where useful). The DSN uses the local default for brevity — replace it in real use.

use Darkterminal\TursoHttp\LibSQL;

$db = new LibSQL(
    'dbname=http://127.0.0.1:8081&authToken=<token>'
);
echo $db->version(), PHP_EOL;   // sqld 0.24.33 (…)

DDL / DML

execute() returns the number of affected rows as an int:

$db->execute('CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)');
$db->execute('INSERT INTO users (name) VALUES (?)', ['Ada']);
$n = $db->execute('UPDATE users SET name = ? WHERE name = ?', ['Ada Lovelace', 'Ada']);
// $n === 1

Fetch modes

$assoc = $db->query('SELECT * FROM users ORDER BY id')->fetchArray(LibSQL::LIBSQL_ASSOC);
// [ ['id' => 1, 'name' => 'Ada Lovelace'], … ]

$num = $db->query('SELECT id, name FROM users WHERE name = ?', ['Ada Lovelace'])
    ->fetchArray(LibSQL::LIBSQL_NUM);
// [ [1, 'Ada Lovelace'] ]

Modes:

Mode Returns
LIBSQL_ASSOC list of associative rows
LIBSQL_NUM list of array_values rows
LIBSQL_BOTH (default) each row merged assoc + numeric keys
LIBSQL_ALL the raw normalized result payload (not rows)

Hrana v3 typed cells ({"type":"integer","value":"7"}) are decoded once at construction, so fetchers behave identically against v2/v3 responses.

Transactions

Explicit transactions (see also the one-liner $builder->transactions([...]) in Query Builder):

$tx = $db->transaction('deferred');
$tx->execute('INSERT INTO accounts (balance) VALUES (?)', [1000]);
$tx->query('SELECT balance FROM accounts WHERE id = ?', [$id]);
$tx->commit();          // or $tx->rollback();

After commit(), rows are visible to subsequent queries. After rollback(), they are not. (Both paths verified against local sqld.)

Failures

Server errors (e.g. no such table: users) surface as a Darkterminal\TursoHttp\core\LibSQLError exception. Nothing calls exit()/die() inside the library — failures are always catchable.

Notes

  • Parameters are positional (?), bound as Hrana typed values.
  • executeBatch() sends multiple statements in a single pipeline request.
  • prepare() returns a LibSQLStatement for reuse of a bound statement.
  • The library speaks Hrana v2 (raw values) and Hrana v3 (typed cells); both are normalized before fetch.

Clone this wiki locally