Skip to main content

oxilite_dylib/
lib.rs

1//! oxilite backend that loads a SQLite shared library from a path at runtime.
2//!
3//! Only the stable SQLite C API functions oxilite needs are resolved, so any SQLite ≥ 3.37
4//! build works (system `libsqlite3`, a vendor-provided library, SQLCipher, …). No SQLite is
5//! linked at build time.
6//!
7// @lat: [[architecture#Backends#Dynamic libsqlite3]]
8
9#![allow(clippy::missing_transmute_annotations, clippy::type_complexity)]
10
11use libloading::Library;
12use oxilite_core::sql::{Capabilities, Mode, Request, Response, ResultSet, SqlValue};
13use oxilite_core::{Error, Result, SyncBackend};
14use std::ffi::{c_char, c_int, c_void, CStr, CString};
15use std::path::Path;
16use std::ptr;
17use std::sync::Mutex;
18
19const SQLITE_OK: c_int = 0;
20const SQLITE_ROW: c_int = 100;
21const SQLITE_DONE: c_int = 101;
22const SQLITE_INTEGER: c_int = 1;
23const SQLITE_FLOAT: c_int = 2;
24const SQLITE_NULL: c_int = 5;
25const SQLITE_OPEN_READONLY: c_int = 0x0000_0001;
26const SQLITE_OPEN_READWRITE: c_int = 0x0000_0002;
27const SQLITE_OPEN_CREATE: c_int = 0x0000_0004;
28const SQLITE_OPEN_URI: c_int = 0x0000_0040;
29const SQLITE_OPEN_NOMUTEX: c_int = 0x0000_8000;
30
31type Db = *mut c_void;
32type Stmt = *mut c_void;
33
34#[allow(clippy::type_complexity)]
35struct Api {
36    open_v2: unsafe extern "C" fn(*const c_char, *mut Db, c_int, *const c_char) -> c_int,
37    close_v2: unsafe extern "C" fn(Db) -> c_int,
38    prepare_v2:
39        unsafe extern "C" fn(Db, *const c_char, c_int, *mut Stmt, *mut *const c_char) -> c_int,
40    step: unsafe extern "C" fn(Stmt) -> c_int,
41    finalize: unsafe extern "C" fn(Stmt) -> c_int,
42    column_count: unsafe extern "C" fn(Stmt) -> c_int,
43    column_type: unsafe extern "C" fn(Stmt, c_int) -> c_int,
44    column_int64: unsafe extern "C" fn(Stmt, c_int) -> i64,
45    column_double: unsafe extern "C" fn(Stmt, c_int) -> f64,
46    column_text: unsafe extern "C" fn(Stmt, c_int) -> *const u8,
47    column_bytes: unsafe extern "C" fn(Stmt, c_int) -> c_int,
48    errmsg: unsafe extern "C" fn(Db) -> *const c_char,
49    changes: unsafe extern "C" fn(Db) -> c_int,
50    exec: unsafe extern "C" fn(
51        Db,
52        *const c_char,
53        *const c_void,
54        *mut c_void,
55        *mut *mut c_char,
56    ) -> c_int,
57    busy_timeout: unsafe extern "C" fn(Db, c_int) -> c_int,
58    libversion_number: unsafe extern "C" fn() -> c_int,
59}
60
61/// A SQLite shared library loaded at runtime.
62pub struct SqliteLibrary {
63    api: Api,
64    _lib: Library,
65}
66
67impl SqliteLibrary {
68    /// Loads the library and resolves the needed symbols.
69    pub fn load(path: impl AsRef<Path>) -> Result<Self> {
70        let path = path.as_ref();
71        // SAFETY: loading a library runs its initializers; the caller chose a SQLite library.
72        let lib = unsafe { Library::new(path) }.map_err(|e| {
73            Error::backend(format!(
74                "cannot load SQLite library {}: {e}",
75                path.display()
76            ))
77        })?;
78        macro_rules! sym {
79            ($name:literal) => {{
80                // SAFETY: the symbol has the documented SQLite C signature.
81                let s = unsafe { lib.get::<*const c_void>(concat!($name, "\0").as_bytes()) }
82                    .map_err(|e| Error::backend(format!("{} is missing symbol {}: {e}", path.display(), $name)))?;
83                // SAFETY: transmuting a function pointer obtained from the library to its known signature.
84                unsafe { std::mem::transmute::<*const c_void, _>(*s) }
85            }};
86        }
87        let api = Api {
88            open_v2: sym!("sqlite3_open_v2"),
89            close_v2: sym!("sqlite3_close_v2"),
90            prepare_v2: sym!("sqlite3_prepare_v2"),
91            step: sym!("sqlite3_step"),
92            finalize: sym!("sqlite3_finalize"),
93            column_count: sym!("sqlite3_column_count"),
94            column_type: sym!("sqlite3_column_type"),
95            column_int64: sym!("sqlite3_column_int64"),
96            column_double: sym!("sqlite3_column_double"),
97            column_text: sym!("sqlite3_column_text"),
98            column_bytes: sym!("sqlite3_column_bytes"),
99            errmsg: sym!("sqlite3_errmsg"),
100            changes: sym!("sqlite3_changes"),
101            exec: sym!("sqlite3_exec"),
102            busy_timeout: sym!("sqlite3_busy_timeout"),
103            libversion_number: sym!("sqlite3_libversion_number"),
104        };
105        Ok(Self { api, _lib: lib })
106    }
107
108    /// `sqlite3_libversion_number()`.
109    pub fn version_number(&self) -> i32 {
110        // SAFETY: no arguments.
111        unsafe { (self.api.libversion_number)() }
112    }
113}
114
115struct Conn {
116    db: Db,
117}
118
119// SAFETY: the connection is only used behind a Mutex (opened with SQLITE_OPEN_NOMUTEX).
120unsafe impl Send for Conn {}
121
122/// Backend over a dynamically loaded SQLite.
123pub struct DylibBackend {
124    lib: SqliteLibrary,
125    conn: Mutex<Conn>,
126    caps: Capabilities,
127}
128
129impl DylibBackend {
130    /// Loads `library` and opens (or creates) `database` (`":memory:"` for in-memory).
131    pub fn open(library: impl AsRef<Path>, database: &str) -> Result<Self> {
132        Self::open_with_flags(
133            library,
134            database,
135            SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE,
136        )
137    }
138
139    /// Loads `library` and opens `database` read-only.
140    pub fn open_read_only(library: impl AsRef<Path>, database: &str) -> Result<Self> {
141        Self::open_with_flags(library, database, SQLITE_OPEN_READONLY)
142    }
143
144    fn open_with_flags(library: impl AsRef<Path>, database: &str, flags: c_int) -> Result<Self> {
145        let lib = SqliteLibrary::load(library)?;
146        let version = lib.version_number();
147        if version < 3_037_000 {
148            return Err(Error::backend(format!(
149                "SQLite library version {version} is too old, oxilite needs 3.37 or newer"
150            )));
151        }
152        let name = CString::new(database).map_err(|e| Error::backend(e.to_string()))?;
153        let mut db: Db = ptr::null_mut();
154        // SAFETY: valid C string and out pointer.
155        let rc = unsafe {
156            (lib.api.open_v2)(
157                name.as_ptr(),
158                &mut db,
159                flags | SQLITE_OPEN_URI | SQLITE_OPEN_NOMUTEX,
160                ptr::null(),
161            )
162        };
163        if rc != SQLITE_OK {
164            let msg = if db.is_null() {
165                format!("error code {rc}")
166            } else {
167                errmsg(&lib, db)
168            };
169            if !db.is_null() {
170                // SAFETY: db was allocated by open_v2.
171                unsafe { (lib.api.close_v2)(db) };
172            }
173            return Err(Error::backend(format!("cannot open {database}: {msg}")));
174        }
175        // SAFETY: db is open.
176        unsafe { (lib.api.busy_timeout)(db, 30_000) };
177        let me = Self {
178            caps: Capabilities {
179                name: format!("dylib (SQLite {version})"),
180                ..Capabilities::native()
181            },
182            lib,
183            conn: Mutex::new(Conn { db }),
184        };
185        if flags & SQLITE_OPEN_READWRITE != 0 && database != ":memory:" {
186            me.exec("PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL")?;
187        }
188        Ok(me)
189    }
190
191    fn exec(&self, sql: &str) -> Result<()> {
192        let conn = self
193            .conn
194            .lock()
195            .unwrap_or_else(std::sync::PoisonError::into_inner);
196        exec(&self.lib, conn.db, sql)
197    }
198}
199
200fn errmsg(lib: &SqliteLibrary, db: Db) -> String {
201    // SAFETY: errmsg returns a NUL-terminated string owned by SQLite.
202    unsafe { CStr::from_ptr((lib.api.errmsg)(db)) }
203        .to_string_lossy()
204        .into_owned()
205}
206
207fn exec(lib: &SqliteLibrary, db: Db, sql: &str) -> Result<()> {
208    let c = CString::new(sql).map_err(|e| Error::backend(e.to_string()))?;
209    // SAFETY: valid db and C string; no callback.
210    let rc = unsafe {
211        (lib.api.exec)(
212            db,
213            c.as_ptr(),
214            ptr::null(),
215            ptr::null_mut(),
216            ptr::null_mut(),
217        )
218    };
219    if rc != SQLITE_OK {
220        return Err(Error::backend(errmsg(lib, db)));
221    }
222    Ok(())
223}
224
225fn run(lib: &SqliteLibrary, db: Db, sql: &str) -> Result<ResultSet> {
226    let c = CString::new(sql).map_err(|e| Error::backend(e.to_string()))?;
227    let mut stmt: Stmt = ptr::null_mut();
228    // SAFETY: valid db and statement out pointer.
229    let rc = unsafe { (lib.api.prepare_v2)(db, c.as_ptr(), -1, &mut stmt, ptr::null_mut()) };
230    if rc != SQLITE_OK {
231        return Err(Error::backend(errmsg(lib, db)));
232    }
233    if stmt.is_null() {
234        return Ok(ResultSet::default());
235    }
236    struct Finalize<'a>(&'a SqliteLibrary, Stmt);
237    impl Drop for Finalize<'_> {
238        fn drop(&mut self) {
239            // SAFETY: the statement was prepared and is finalized once.
240            unsafe { (self.0.api.finalize)(self.1) };
241        }
242    }
243    let _guard = Finalize(lib, stmt);
244    // SAFETY: stmt is a valid prepared statement for all calls below.
245    let n = unsafe { (lib.api.column_count)(stmt) };
246    let mut rows = Vec::new();
247    loop {
248        let rc = unsafe { (lib.api.step)(stmt) };
249        match rc {
250            SQLITE_ROW => {
251                let mut row = Vec::with_capacity(n as usize);
252                for i in 0..n {
253                    row.push(match unsafe { (lib.api.column_type)(stmt, i) } {
254                        SQLITE_NULL => SqlValue::Null,
255                        SQLITE_INTEGER => {
256                            SqlValue::Integer(unsafe { (lib.api.column_int64)(stmt, i) })
257                        }
258                        SQLITE_FLOAT => SqlValue::Real(unsafe { (lib.api.column_double)(stmt, i) }),
259                        _ => {
260                            let p = unsafe { (lib.api.column_text)(stmt, i) };
261                            let len = unsafe { (lib.api.column_bytes)(stmt, i) } as usize;
262                            if p.is_null() {
263                                SqlValue::Text(String::new())
264                            } else {
265                                let bytes = unsafe { std::slice::from_raw_parts(p, len) };
266                                SqlValue::Text(String::from_utf8_lossy(bytes).into_owned())
267                            }
268                        }
269                    });
270                }
271                rows.push(row);
272            }
273            SQLITE_DONE => break,
274            _ => return Err(Error::backend(errmsg(lib, db))),
275        }
276    }
277    let changes = if n == 0 {
278        // SAFETY: valid db.
279        u64::try_from(unsafe { (lib.api.changes)(db) }).unwrap_or(0)
280    } else {
281        0
282    };
283    Ok(ResultSet { rows, changes })
284}
285
286impl SyncBackend for DylibBackend {
287    fn execute(&self, request: &Request) -> Result<Response> {
288        if request.statements.iter().any(|s| !s.params.is_empty()) {
289            return Err(Error::unsupported("bound parameters on the dylib backend"));
290        }
291        let conn = self
292            .conn
293            .lock()
294            .unwrap_or_else(std::sync::PoisonError::into_inner);
295        let db = conn.db;
296        match request.mode {
297            Mode::Read => request
298                .statements
299                .iter()
300                .map(|s| run(&self.lib, db, &s.sql))
301                .collect(),
302            Mode::Atomic => {
303                exec(&self.lib, db, "SAVEPOINT oxilite_request")?;
304                let r: Result<Response> = request
305                    .statements
306                    .iter()
307                    .map(|s| run(&self.lib, db, &s.sql))
308                    .collect();
309                match r {
310                    Ok(r) => {
311                        exec(&self.lib, db, "RELEASE oxilite_request")?;
312                        Ok(r)
313                    }
314                    Err(e) => {
315                        let _ = exec(
316                            &self.lib,
317                            db,
318                            "ROLLBACK TO oxilite_request; RELEASE oxilite_request",
319                        );
320                        Err(e)
321                    }
322                }
323            }
324        }
325    }
326
327    fn capabilities(&self) -> &Capabilities {
328        &self.caps
329    }
330
331    fn begin(&self) -> Result<()> {
332        self.exec("SAVEPOINT oxilite_tx")
333    }
334
335    fn commit(&self) -> Result<()> {
336        self.exec("RELEASE oxilite_tx")
337    }
338
339    fn rollback(&self) -> Result<()> {
340        self.exec("ROLLBACK TO oxilite_tx; RELEASE oxilite_tx")
341    }
342}
343
344impl Drop for DylibBackend {
345    fn drop(&mut self) {
346        let conn = self
347            .conn
348            .get_mut()
349            .unwrap_or_else(std::sync::PoisonError::into_inner);
350        if !conn.db.is_null() {
351            // SAFETY: closes the connection opened in open_with_flags.
352            unsafe { (self.lib.api.close_v2)(conn.db) };
353            conn.db = ptr::null_mut();
354        }
355    }
356}
357
358/// Well-known locations of a system SQLite library, for tests and examples.
359pub fn system_library_candidates() -> &'static [&'static str] {
360    if cfg!(target_os = "macos") {
361        &[
362            "/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib",
363            "/usr/local/opt/sqlite/lib/libsqlite3.dylib",
364            "/usr/lib/libsqlite3.dylib",
365        ]
366    } else if cfg!(windows) {
367        &["sqlite3.dll"]
368    } else {
369        &[
370            "libsqlite3.so.0",
371            "/usr/lib/x86_64-linux-gnu/libsqlite3.so.0",
372            "/usr/lib/libsqlite3.so",
373        ]
374    }
375}
376
377/// The library named by `OXILITE_SQLITE_LIBRARY`, or the first loadable system SQLite.
378pub fn find_system_library() -> Option<&'static str> {
379    if let Ok(p) = std::env::var("OXILITE_SQLITE_LIBRARY") {
380        return Some(Box::leak(p.into_boxed_str()));
381    }
382    system_library_candidates()
383        .iter()
384        .copied()
385        .find(|p| SqliteLibrary::load(p).is_ok_and(|l| l.version_number() >= 3_037_000))
386}
387
388#[cfg(test)]
389mod tests {
390    use super::*;
391
392    // @tg: verifies:: [[tests#Backends#Dylib loads a system SQLite]] {since: "2026-09-22", level: unit}
393    #[test]
394    fn dylib_loads_a_system_sqlite() {
395        let Some(lib) = find_system_library() else {
396            eprintln!("no system SQLite ≥ 3.37 found, skipping");
397            return;
398        };
399        let b = DylibBackend::open(lib, ":memory:").unwrap();
400        let r = b
401            .execute(&Request::read(vec!["SELECT 1 + 1, 'x', 2.5, NULL".into()]))
402            .unwrap();
403        assert_eq!(
404            r[0].rows[0],
405            vec![
406                SqlValue::Integer(2),
407                SqlValue::Text("x".into()),
408                SqlValue::Real(2.5),
409                SqlValue::Null
410            ]
411        );
412        b.execute(&Request::atomic(vec![
413            "CREATE TABLE t (x INTEGER PRIMARY KEY)".into(),
414        ]))
415        .unwrap();
416        assert!(b
417            .execute(&Request::atomic(vec![
418                "INSERT INTO t VALUES (1)".into(),
419                "INSERT INTO t VALUES (1)".into()
420            ]))
421            .is_err());
422        let r = b
423            .execute(&Request::read(vec!["SELECT COUNT(*) FROM t".into()]))
424            .unwrap();
425        assert_eq!(r[0].rows[0][0], SqlValue::Integer(0));
426    }
427
428    // @tg: verifies:: [[tests#Backends#Invalid library is reported]] {since: "2026-09-22", level: unit}
429    #[test]
430    fn invalid_library_is_reported() {
431        let e = DylibBackend::open("/nonexistent/libsqlite3.so", ":memory:")
432            .err()
433            .unwrap();
434        assert!(e.to_string().contains("cannot load SQLite library"), "{e}");
435    }
436}