libsql

Use libSQL from Gleam!

This is a Gleam library for libSQL with the same ergonomics as sqlight, built on a Rust NIF that wraps the official libsql crate.

Features

Requirements

No Rust toolchain is required for end-users — precompiled NIF binaries are downloaded automatically for supported platforms (Linux x86_64, macOS x86_64, macOS aarch64). For other platforms, Rust & Cargo are needed to build from source.

Building from source

If a precompiled binary is not available for your platform, compile the NIF locally:

make build

Or manually:

cd native/libsql_nif && cargo build --release
cp target/release/liblibsql_nif.so ../../priv/libsql_nif.so  # Linux
# cp target/release/liblibsql_nif.dylib ../../priv/libsql_nif.dylib  # macOS

Running tests

make test

Usage

import gleam/dynamic/decode
import libsql

pub fn main() {
  use conn <- libsql.with_connection(":memory:")

  let sql = "
  create table cats (name text, age int);

  insert into cats (name, age) values
  ('Nubi', 4),
  ('Biffy', 10),
  ('Ginny', 6);
  "
  let assert Ok(Nil) = libsql.exec(sql, conn)

  let cat_decoder = {
    use name <- decode.field(0, decode.string)
    use age <- decode.field(1, decode.int)
    decode.success(#(name, age))
  }

  let sql = "
  select name, age from cats
  where age < ?
  "
  let assert Ok([#("Nubi", 4), #("Ginny", 6)]) =
    libsql.query(sql, on: conn, with: [libsql.int(7)], expecting: cat_decoder)
}

Remote connection

import gleam/dynamic/decode
import libsql

pub fn main() {
  let url = "libsql://my-db.turso.io"
  let token = "my-auth-token"
  use conn <- libsql.with_remote_connection(url, token)

  let assert Ok([#("hello", 42)]) =
    libsql.query(
      "select 'hello', 42",
      on: conn,
      with: [],
      expecting: {
        use a <- decode.field(0, decode.string)
        use b <- decode.field(1, decode.int)
        decode.success(#(a, b))
      },
    )
}

Transactions

pub fn insert_user(conn, name, age) {
  libsql.transaction(conn, fn() {
    use _ <- result.try(libsql.exec("insert into users (name) values (?)", conn))
    use _ <- result.try(libsql.exec("insert into logs (action) values ('created')", conn))
    Ok(Nil)
  })
}

If the inner function returns Error(...), the transaction is automatically rolled back.

Named parameters

libsql.query_named(
  "select * from cats where name = :name and age > :min_age",
  conn,
  [
    #$(":name", libsql.text("Nubi")),
    #$(":min_age", libsql.int(2)),
  ],
  expecting: cat_decoder,
)

Batch execution

libsql.exec_batch(
  "insert into users (name, age) values (?, ?)",
  conn,
  [
    [libsql.text("Alice"), libsql.int(30)],
    [libsql.text("Bob"), libsql.int(25)],
    [libsql.text("Carol"), libsql.int(35)],
  ],
)

Batch operations are typically wrapped in a transaction for atomicity:

libsql.transaction(conn, fn() {
  libsql.exec_batch(
    "insert into logs (action) values (?)",
    conn,
    actions |> list.map(fn(a) { [libsql.text(a)] }),
  )
})

Convenience helpers

Single-row queries:

// Expect exactly one row — errors on 0 or multiple
let assert Ok(user) =
  libsql.query_one(
    "select * from users where id = ?",
    conn,
    [libsql.int(42)],
    user_decoder,
  )

// Get the first row (or None)
let assert Ok(option.Some(user)) =
  libsql.query_first(
    "select * from users where email = ?",
    conn,
    [libsql.text("alice@example.com")],
    user_decoder,
  )

Insert metadata:

let assert Ok(Nil) = libsql.exec("insert into users (name) values ('Alice')", conn)
let assert Ok(id) = libsql.last_insert_rowid(conn)

let assert Ok(Nil) = libsql.exec("update users set active = 1", conn)
let assert Ok(3) = libsql.changes(conn)

Prepared statements

libsql.with_statement("insert into users (name, age) values (?, ?)", conn, fn(stmt) {
  let assert Ok(Nil) = libsql.exec_prepared(stmt, [libsql.text("Alice"), libsql.int(30)])
  let assert Ok(Nil) = libsql.exec_prepared(stmt, [libsql.text("Bob"), libsql.int(25)])
})

Prepared statements avoid re-parsing SQL on each execution, giving a significant performance boost for repeated queries.

Embedded replica

let db_path = "/tmp/my_replica.db"
let url = "libsql://my-db.turso.io"
let token = "my-auth-token"

let assert Ok(conn) = libsql.open_replica(db_path, url, token)

// Sync with remote primary
let assert Ok(replicated) = libsql.sync(conn)
// replicated.frame_no    -> Option(Int)
// replicated.frames_synced -> Int

// Queries are served from the local replica
let assert Ok([#("hello", 42)]) =
  libsql.query(
    "select 'hello', 42",
    conn,
    [],
    expecting: {
      use a <- decode.field(0, decode.string)
      use b <- decode.field(1, decode.int)
      decode.success(#(a, b))
    },
  )

Synced database (offline writes)

Unlike a replica (which delegates writes to the remote), a synced database keeps writes local and pushes them when you call sync():

let db_path = "/tmp/my_synced.db"
let url = "libsql://my-db.turso.io"
let token = "my-auth-token"

let assert Ok(conn) = libsql.open_synced_database(db_path, url, token)

// Pull remote state first (recommended)
let assert Ok(_) = libsql.sync(conn)

// Writes are local and work offline
let assert Ok(Nil) = libsql.exec("create table todos (id integer primary key, task text)", conn)
let assert Ok(Nil) = libsql.exec("insert into todos (task) values ('Buy milk')", conn)

// Read locally at full SQLite speed
let assert Ok(["Buy milk"]) =
  libsql.query(
    "select task from todos",
    conn,
    [],
    decode.field(0, decode.string, decode.success),
  )

// Push local changes to remote
let assert Ok(replicated) = libsql.sync(conn)

API

The API mirrors sqlight closely:

Architecture

┌─────────────────┐
│   Gleam API     │  src/libsql.gleam
├─────────────────┤
│ Erlang FFI shim │  src/libsql_ffi.erl
├─────────────────┤
│   Rust NIF      │  native/libsql_nif/src/lib.rs
├─────────────────┤
│   libsql crate  │  (Rust) – wraps SQLite C + remote protocol
└─────────────────┘

Future work

License

Apache-2.0