Crate libsql

libSQL API for Rust

libSQL is an embeddable SQL database engine based on SQLite. This Rust API is a batteries-included wrapper around the SQLite C API to support transparent replication while retaining compatibility with the SQLite ecosystem, such as the SQL dialect and extensions. If you are building an application in Rust, this is the crate you should use. There are also libSQL language bindings of this Rust crate to other languages such as JavaScript, Python, Go, and C.

Getting Started

To get started, you first need to create a Database object and then open a Connection to it, which you use to query:

use libsql::Database;

let db = Database::open_in_memory().unwrap();
let conn = db.connect().unwrap();
conn.execute("CREATE TABLE IF NOT EXISTS users (email TEXT)", ()).await.unwrap();
conn.execute("INSERT INTO users (email) VALUES ('alice@example.org')", ()).await.unwrap();

Embedded Replicas

Embedded replica is libSQL database that’s running in your application process, which keeps a local copy of a remote database. They are useful if you want to move data in the memory space of your application for fast access.

You can open an embedded read-only replica by using the Database::open_with_local_sync constructor:

use libsql::{Database, Frames};

let mut db = Database::open_with_local_sync("/tmp/test.db").await.unwrap();

let frames = Frames::Vec(vec![]);
db.sync_frames(frames).await.unwrap();
let conn = db.connect().unwrap();
conn.execute("SELECT * FROM users", ()).await.unwrap();

WASM

Due to WASM requiring !Send support and the Database type supporting async and using async_trait to abstract between the different database types, we are unable to support WASM via the Database type. Instead, we have provided simpler parallel types in the wasm module that provide access to our remote HTTP protocol in WASM.

Examples

You can find more examples in the examples directory.

Re-exports

• pub use errors::Error;
• pub use params::params_from_iter;

Modules

• de
  Deserialization utilities.
• errors
• fficore
  C ffi for libsql.
• params
  This module contains all Param related utilities and traits.
• replicationreplication
  Utilities used when using a replicated version of libsql.
• wasmwasm
  This module contains a special Connection struct that can be used in constrained wasm environments. This struct is separate from the main connection struct in the root of the crate due to the nature of some wasm clients requiring !Send/!Sync support.

Macros

• named_params
  Construct named params from a hetergeneous set of params types.
• params
  Construct positional params from a hetergeneous set of params types.

Structs

• Column
  Represents a libsql column.
• Connection
  A connection to some libsql database, this can be a remote one or a local one.
• Database
  A struct that knows how to build Connection’s, this type does not do much work until the Database::connect fn is called.
• OpenFlagscore
  Flags that can be passed to libsql to open a database in specific modes.
• Row
  A libsql row.
• Rows
  A set of rows returned from a connection.
• RowsFuturecore
• Statement
  A cached prepared statement.
• Transaction
  A transaction on some connection.

Enums

• TransactionBehavior
  Transaction types that correlate to sqlite3 transactions and additional ones introduced by libsql.
• Value
• ValueRef
  A borrowed version of Value.
• ValueType
  The possible types a column can be in libsql.

Functions

• versioncore
  Return the version of the underlying SQLite library as a string.
• version_numbercore
  Return the version of the underlying SQLite library as a number.

Type Aliases

• Result
  Convenient alias for Result using the libsql::Error type.