Skip to content

Query Builder

darkterminal edited this page Nov 11, 2026 · 1 revision

Query Builder

A fluent query builder ships in the package (backed by the same pipeline protocol — no PHP extension involved). All examples below mirror the feature tests (tests/Feature/QueryBuilder/*), which run in CI.

use Darkterminal\TursoHttp\LibSQL;
use Darkterminal\TursoHttp\core\Builder\LibSQLQueryBuilder;

$db      = new LibSQL('dbname=…&authToken=…');
$builder = new LibSQLQueryBuilder($db);

Reads

$data = $builder->table('users')->get();        // all rows
$one  = $builder->get('users');                  // same, table as argument

$data = $builder->table('users')
    ->where('age', '>', 30)
    ->orderBy('name', 'ASC')
    ->get();

get() returns a plain array of rows (usually decoded values, timezone rules applied — see Configuration).

Writes

$builder->table('users')->insert(['name' => 'Ada']);            // one row
$builder->table('users')->insertBatch([                          // many rows
    ['name' => 'Grace'], ['name' => 'Edsger'],
]);

$builder->table('users')->where('name', 'Ada')->update(['name' => 'Ada Lovelace']);
$builder->table('users')->where('name', 'Grace')->delete();

RETURNING statements

$data = $builder->insertReturn('book_lists', ['title' => 'X', 'isbn' => '…'], ['title', 'isbn']);
$data = $builder->updateReturn('book_lists', ['isbn' => '0141439512'], sqlite_equal('id', 1));
$data = $builder->deleteReturn('book_lists', sqlite_equal('id', 1));

*Return methods execute … RETURNING … and return the decoded rows.

UPSERT

$onInsert = ['name' => 'Jane', 'email' => 'jane@test.com', 'effective_date' => '2024-05-05'];
$onUpdate = ['name' => $builder->rawValue('excluded.name')];

$builder->upsert('contacts', $onInsert, $onUpdate, 'email'); // conflict target

Multi-statement transactions

$queries[] = $builder->table('accounts')->where('account_no', '=', 100)
    ->update(['balance' => $builder->rawValue('balance - 1000')], true);   // last arg: return SQL instead of executing
$queries[] = $builder->table('account_changes')
    ->insert(['account_no' => 100, 'flag' => '-', 'amount' => 1000,
              'changed_at' => $builder->rawValue("datetime('now')")], true);

$ok = $builder->transactions($queries);  // true on success

Notes

  • rawValue() embeds an expression verbatim (used for expressions like balance - 1000 or datetime('now')). Use it only for trusted expressions — it is not escaped.
  • sqlite_equal('id', 1) produces a safe bound condition for *Return* helpers.
  • For plain parameters, prefer positional ? with LibSQL::query() (see Basic Usage).
  • Vector search: there is no vector-cast helper — use raw SQL vector(…) like with the native client.
  • Strict-query mode (DB_STRICT_QUERY=true) routes queries through EXPLAIN when set; the default is off.

Clone this wiki locally