25 releases (5 breaking)

0.6.0 Sep 20, 2024
0.5.0-alpha.2 Jul 11, 2024
0.3.2 Mar 26, 2024
0.1.11 Sep 7, 2023
0.1.0 Nov 26, 2022

#57 in Database interfaces

Download history 1385/week @ 2024-07-17 2771/week @ 2024-07-24 2042/week @ 2024-07-31 1907/week @ 2024-08-07 2365/week @ 2024-08-14 3155/week @ 2024-08-21 3363/week @ 2024-08-28 3566/week @ 2024-09-04 3859/week @ 2024-09-11 3852/week @ 2024-09-18 4130/week @ 2024-09-25 4189/week @ 2024-10-02 3056/week @ 2024-10-09 3651/week @ 2024-10-16 3587/week @ 2024-10-23 2253/week @ 2024-10-30

13,194 downloads per month
Used in 22 crates (19 directly)

MIT license

415KB
10K SLoC

libSQL API for Rust

Crates.io MIT licensed

This repository contains the libSQL API for Rust.

Developing

See DEVELOPING.md for more information.

License

This project is licensed under the MIT license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in libSQL by you, shall be licensed as MIT, without any additional terms or conditions.


lib.rs:

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::Builder;

let db = Builder::new_local(":memory:").build().await.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::Builder;
use libsql::replication::Frames;

let mut db = Builder::new_local_replica("/tmp/test.db").build().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();

Remote database

It is also possible to create a libsql connection that does not open a local database but instead sends queries to a remote database.

use libsql::Builder;

let db = Builder::new_remote("libsql://my-remote-db.com".to_string(), "my-auth-token".to_string()).build().await.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();

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.

Feature flags

This crate provides a few feature flags that will help you improve compile times by allowing you to reduce the dependencies needed to compile specific features of this crate. For example, you may not want to compile the libsql C code if you just want to make HTTP requests. Feature flags may be used by including the libsql crate like:

libsql = { version = "*", default-features = false, features = ["core", "replication", "remote" ]

By default, all the features are enabled but by providing default-features = false it will remove those defaults.

The features are descirbed like so:

  • core this includes the core C code that backs both the basic local database usage and embedded replica features.
  • replication this feature flag includes the core feature flag and adds on top HTTP code that will allow you to sync you remote database locally.
  • remote this feature flag only includes HTTP code that will allow you to run queries against a remote database.
  • tls this feature flag disables the builtin TLS connector and instead requires that you pass your own connector for any of the features that require HTTP.

Dependencies

~0.5–16MB
~219K SLoC