diesel_libsql/lib.rs
1//! A [Diesel](https://diesel.rs) backend for [libSQL](https://turso.tech/libsql)
2//! (Turso's SQLite-compatible database).
3//!
4//! This crate lets you use Diesel's typed query builder, migrations, and
5//! connection traits against local SQLite files, remote Turso databases, and
6//! embedded replicas -- all through a single [`LibSqlConnection`] type.
7//!
8//! # Why not `diesel::sqlite`?
9//!
10//! - **ALTER COLUMN**: libSQL extends SQLite with `ALTER TABLE ... ALTER COLUMN`,
11//! exposed here via [`LibSqlConnection::alter_column`].
12//! - **Remote Turso**: connect to `libsql://` URLs with auth tokens.
13//! - **Embedded replicas**: local reads with remote sync via
14//! [`LibSqlConnection::establish_replica`].
15//!
16//! # Quick start
17//!
18//! ```rust,no_run
19//! use diesel::prelude::*;
20//! use diesel_libsql::LibSqlConnection;
21//!
22//! let mut conn = LibSqlConnection::establish(":memory:")
23//! .expect("Failed to connect");
24//!
25//! diesel::sql_query("CREATE TABLE demo (id INTEGER PRIMARY KEY, val TEXT)")
26//! .execute(&mut conn)
27//! .unwrap();
28//! ```
29//!
30//! # Feature flags
31//!
32//! | Flag | Description |
33//! |--------------|----------------------------------------------------|
34//! | `r2d2` | Sync connection pooling via `r2d2` |
35//! | `async` | Native async connection via `diesel-async` |
36//! | `deadpool` | Async connection pooling via `deadpool` (implies `async`) |
37//! | `bb8` | Async connection pooling via `bb8` (implies `async`) |
38//! | `otel` | `OtelInstrumentation` for OpenTelemetry spans |
39//! | `encryption` | AES-256 encryption at rest via `establish_encrypted` (requires `cmake`) |
40
41mod backend;
42mod bind_collector;
43mod connection;
44mod from_sql;
45mod query_builder;
46mod row;
47mod to_sql;
48mod value;
49
50/// Sync connection pooling via `r2d2`. Requires the `r2d2` feature.
51#[cfg(feature = "r2d2")]
52pub mod r2d2;
53
54#[cfg(feature = "async")]
55mod async_conn;
56
57/// Async connection pooling via `deadpool`. Requires the `deadpool` feature.
58#[cfg(feature = "deadpool")]
59pub mod deadpool;
60
61/// Async connection pooling via `bb8`. Requires the `bb8` feature.
62#[cfg(feature = "bb8")]
63pub mod bb8;
64
65#[cfg(feature = "otel")]
66mod instrumentation;
67
68pub use backend::LibSql;
69pub use bind_collector::{LibSqlBindCollector, LibSqlBindValue};
70pub use connection::{LibSqlConnection, ReplicaBuilder};
71pub use value::LibSqlValue;
72
73#[cfg(feature = "async")]
74pub use async_conn::{AsyncLibSqlConnection, AsyncLibSqlConnectionExt};
75
76#[cfg(feature = "otel")]
77pub use instrumentation::OtelInstrumentation;