sqlmodel_sqlite/
ffi.rs

1//! Low-level FFI bindings to libsqlite3.
2//!
3//! These bindings are manually written to provide full control over the
4//! interface. We only expose what we need for the driver implementation.
5
6#![allow(non_camel_case_types)]
7#![allow(clippy::upper_case_acronyms)]
8#![allow(clippy::unreadable_literal)] // FFI constants use standard hex format
9
10use std::ffi::{c_char, c_double, c_int, c_void};
11
12/// Opaque sqlite3 database connection handle.
13#[repr(C)]
14pub struct sqlite3 {
15    _private: [u8; 0],
16}
17
18/// Opaque sqlite3_stmt prepared statement handle.
19#[repr(C)]
20pub struct sqlite3_stmt {
21    _private: [u8; 0],
22}
23
24/// Opaque sqlite3_backup handle.
25#[repr(C)]
26pub struct sqlite3_backup {
27    _private: [u8; 0],
28}
29
30// SQLite result codes
31pub const SQLITE_OK: c_int = 0;
32pub const SQLITE_ERROR: c_int = 1;
33pub const SQLITE_INTERNAL: c_int = 2;
34pub const SQLITE_PERM: c_int = 3;
35pub const SQLITE_ABORT: c_int = 4;
36pub const SQLITE_BUSY: c_int = 5;
37pub const SQLITE_LOCKED: c_int = 6;
38pub const SQLITE_NOMEM: c_int = 7;
39pub const SQLITE_READONLY: c_int = 8;
40pub const SQLITE_INTERRUPT: c_int = 9;
41pub const SQLITE_IOERR: c_int = 10;
42pub const SQLITE_CORRUPT: c_int = 11;
43pub const SQLITE_NOTFOUND: c_int = 12;
44pub const SQLITE_FULL: c_int = 13;
45pub const SQLITE_CANTOPEN: c_int = 14;
46pub const SQLITE_PROTOCOL: c_int = 15;
47pub const SQLITE_EMPTY: c_int = 16;
48pub const SQLITE_SCHEMA: c_int = 17;
49pub const SQLITE_TOOBIG: c_int = 18;
50pub const SQLITE_CONSTRAINT: c_int = 19;
51pub const SQLITE_MISMATCH: c_int = 20;
52pub const SQLITE_MISUSE: c_int = 21;
53pub const SQLITE_NOLFS: c_int = 22;
54pub const SQLITE_AUTH: c_int = 23;
55pub const SQLITE_FORMAT: c_int = 24;
56pub const SQLITE_RANGE: c_int = 25;
57pub const SQLITE_NOTADB: c_int = 26;
58pub const SQLITE_NOTICE: c_int = 27;
59pub const SQLITE_WARNING: c_int = 28;
60pub const SQLITE_ROW: c_int = 100;
61pub const SQLITE_DONE: c_int = 101;
62
63// sqlite3_open_v2 flags
64pub const SQLITE_OPEN_READONLY: c_int = 0x00000001;
65pub const SQLITE_OPEN_READWRITE: c_int = 0x00000002;
66pub const SQLITE_OPEN_CREATE: c_int = 0x00000004;
67pub const SQLITE_OPEN_URI: c_int = 0x00000040;
68pub const SQLITE_OPEN_MEMORY: c_int = 0x00000080;
69pub const SQLITE_OPEN_NOMUTEX: c_int = 0x00008000;
70pub const SQLITE_OPEN_FULLMUTEX: c_int = 0x00010000;
71pub const SQLITE_OPEN_SHAREDCACHE: c_int = 0x00020000;
72pub const SQLITE_OPEN_PRIVATECACHE: c_int = 0x00040000;
73
74// Fundamental data types
75pub const SQLITE_INTEGER: c_int = 1;
76pub const SQLITE_FLOAT: c_int = 2;
77pub const SQLITE_TEXT: c_int = 3;
78pub const SQLITE_BLOB: c_int = 4;
79pub const SQLITE_NULL: c_int = 5;
80
81// Type alias for destructor callback
82pub type sqlite3_destructor_type = Option<unsafe extern "C" fn(*mut c_void)>;
83
84// Special destructor value that tells SQLite to copy the data immediately.
85// SQLITE_TRANSIENT is defined in SQLite as ((void(*)(void*))(-1))
86// We use transmute at runtime since const transmute is unstable.
87/// Returns the SQLITE_TRANSIENT destructor value.
88///
89/// This value tells SQLite to immediately copy any bound string or blob data.
90/// It is the safest option when the source data's lifetime is uncertain.
91#[inline]
92pub fn sqlite_transient() -> sqlite3_destructor_type {
93    // SAFETY: SQLite defines SQLITE_TRANSIENT as a sentinel function pointer
94    // with the value -1. SQLite checks for this sentinel and does not invoke it.
95    const SQLITE_TRANSIENT_SENTINEL: isize = -1;
96    unsafe { std::mem::transmute::<isize, sqlite3_destructor_type>(SQLITE_TRANSIENT_SENTINEL) }
97}
98
99// Statically link sqlite3 on every platform. The `libsqlite3-sys` dep with
100// feature `bundled` (see Cargo.toml) compiles SQLite from the vendored
101// amalgamation and puts `libsqlite3.a` on the rustc native-lib search path
102// via `cargo:rustc-link-search=native=…`. We then declare the static
103// dependency explicitly here because nothing in this crate imports an item
104// from `libsqlite3-sys`, so rustc would otherwise elide its rlib and drop
105// its build-script link directives. Prior to this, the non-Windows attribute
106// was `#[link(name = "sqlite3")]` (dynamic), which:
107//   1. on musl picked up no libsqlite3 at all and failed to link, and
108//   2. on glibc hosts with libsqlite3-dev installed silently bound to the
109//      host libsqlite3.a compiled with FORTIFY_SOURCE, producing unresolved
110//      `__memcpy_chk` symbols when cross-linking for musl.
111// Using `kind = "static"` + the bundled amalgamation gives reproducible
112// behaviour across every supported target.
113#[link(name = "sqlite3", kind = "static")]
114unsafe extern "C" {
115    // Connection management
116    pub fn sqlite3_open(filename: *const c_char, ppDb: *mut *mut sqlite3) -> c_int;
117
118    pub fn sqlite3_open_v2(
119        filename: *const c_char,
120        ppDb: *mut *mut sqlite3,
121        flags: c_int,
122        zVfs: *const c_char,
123    ) -> c_int;
124
125    pub fn sqlite3_close(db: *mut sqlite3) -> c_int;
126    pub fn sqlite3_close_v2(db: *mut sqlite3) -> c_int;
127
128    // Backup API
129    pub fn sqlite3_backup_init(
130        pDest: *mut sqlite3,
131        zDestName: *const c_char,
132        pSource: *mut sqlite3,
133        zSourceName: *const c_char,
134    ) -> *mut sqlite3_backup;
135    pub fn sqlite3_backup_step(p: *mut sqlite3_backup, nPage: c_int) -> c_int;
136    pub fn sqlite3_backup_finish(p: *mut sqlite3_backup) -> c_int;
137    pub fn sqlite3_backup_remaining(p: *mut sqlite3_backup) -> c_int;
138    pub fn sqlite3_backup_pagecount(p: *mut sqlite3_backup) -> c_int;
139
140    // Error handling
141    pub fn sqlite3_errmsg(db: *mut sqlite3) -> *const c_char;
142    pub fn sqlite3_errcode(db: *mut sqlite3) -> c_int;
143    pub fn sqlite3_extended_errcode(db: *mut sqlite3) -> c_int;
144    pub fn sqlite3_errstr(errcode: c_int) -> *const c_char;
145
146    // Statement preparation
147    pub fn sqlite3_prepare_v2(
148        db: *mut sqlite3,
149        zSql: *const c_char,
150        nByte: c_int,
151        ppStmt: *mut *mut sqlite3_stmt,
152        pzTail: *mut *const c_char,
153    ) -> c_int;
154
155    pub fn sqlite3_finalize(pStmt: *mut sqlite3_stmt) -> c_int;
156    pub fn sqlite3_reset(pStmt: *mut sqlite3_stmt) -> c_int;
157    pub fn sqlite3_clear_bindings(pStmt: *mut sqlite3_stmt) -> c_int;
158
159    // Parameter binding
160    pub fn sqlite3_bind_null(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
161
162    pub fn sqlite3_bind_int(pStmt: *mut sqlite3_stmt, index: c_int, value: c_int) -> c_int;
163
164    pub fn sqlite3_bind_int64(pStmt: *mut sqlite3_stmt, index: c_int, value: i64) -> c_int;
165
166    pub fn sqlite3_bind_double(pStmt: *mut sqlite3_stmt, index: c_int, value: c_double) -> c_int;
167
168    pub fn sqlite3_bind_text(
169        pStmt: *mut sqlite3_stmt,
170        index: c_int,
171        value: *const c_char,
172        nBytes: c_int,
173        destructor: sqlite3_destructor_type,
174    ) -> c_int;
175
176    pub fn sqlite3_bind_blob(
177        pStmt: *mut sqlite3_stmt,
178        index: c_int,
179        value: *const c_void,
180        nBytes: c_int,
181        destructor: sqlite3_destructor_type,
182    ) -> c_int;
183
184    pub fn sqlite3_bind_parameter_count(pStmt: *mut sqlite3_stmt) -> c_int;
185    pub fn sqlite3_bind_parameter_index(pStmt: *mut sqlite3_stmt, name: *const c_char) -> c_int;
186    pub fn sqlite3_bind_parameter_name(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
187
188    // Stepping through results
189    pub fn sqlite3_step(pStmt: *mut sqlite3_stmt) -> c_int;
190
191    // Result column information
192    pub fn sqlite3_column_count(pStmt: *mut sqlite3_stmt) -> c_int;
193    pub fn sqlite3_column_name(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
194    pub fn sqlite3_column_type(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
195    pub fn sqlite3_column_decltype(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
196
197    // Result column values
198    pub fn sqlite3_column_int(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
199    pub fn sqlite3_column_int64(pStmt: *mut sqlite3_stmt, index: c_int) -> i64;
200    pub fn sqlite3_column_double(pStmt: *mut sqlite3_stmt, index: c_int) -> c_double;
201    pub fn sqlite3_column_text(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
202    pub fn sqlite3_column_blob(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_void;
203    pub fn sqlite3_column_bytes(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
204
205    // Execution helpers
206    pub fn sqlite3_exec(
207        db: *mut sqlite3,
208        sql: *const c_char,
209        callback: Option<
210            unsafe extern "C" fn(*mut c_void, c_int, *mut *mut c_char, *mut *mut c_char) -> c_int,
211        >,
212        arg: *mut c_void,
213        errmsg: *mut *mut c_char,
214    ) -> c_int;
215
216    pub fn sqlite3_free(ptr: *mut c_void);
217
218    // Metadata
219    pub fn sqlite3_changes(db: *mut sqlite3) -> c_int;
220    pub fn sqlite3_total_changes(db: *mut sqlite3) -> c_int;
221    pub fn sqlite3_last_insert_rowid(db: *mut sqlite3) -> i64;
222
223    // Configuration
224    pub fn sqlite3_busy_timeout(db: *mut sqlite3, ms: c_int) -> c_int;
225
226    // Version info
227    pub fn sqlite3_libversion() -> *const c_char;
228    pub fn sqlite3_libversion_number() -> c_int;
229}
230
231/// Get the SQLite library version as a string.
232pub fn version() -> &'static str {
233    // SAFETY: sqlite3_libversion returns a static string
234    unsafe {
235        let ptr = sqlite3_libversion();
236        std::ffi::CStr::from_ptr(ptr).to_str().unwrap_or("unknown")
237    }
238}
239
240/// Get the SQLite library version as a number.
241pub fn version_number() -> i32 {
242    // SAFETY: sqlite3_libversion_number is always safe to call
243    unsafe { sqlite3_libversion_number() }
244}
245
246/// Convert an SQLite result code to a human-readable string.
247pub fn error_string(code: c_int) -> &'static str {
248    // SAFETY: sqlite3_errstr returns a static string
249    unsafe {
250        let ptr = sqlite3_errstr(code);
251        std::ffi::CStr::from_ptr(ptr)
252            .to_str()
253            .unwrap_or("unknown error")
254    }
255}
256
257#[cfg(test)]
258mod tests {
259    use super::*;
260
261    #[test]
262    fn test_version() {
263        let v = version();
264        assert!(!v.is_empty());
265        // SQLite version should start with 3.
266        assert!(v.starts_with('3'));
267    }
268
269    #[test]
270    fn test_version_number() {
271        let v = version_number();
272        // SQLite 3.x.x version numbers are in the form 3XXYYZZ
273        // e.g., 3.45.0 = 3045000
274        assert!(v >= 3_000_000);
275    }
276
277    #[test]
278    fn test_error_string() {
279        assert_eq!(error_string(SQLITE_OK), "not an error");
280        assert_eq!(error_string(SQLITE_ERROR), "SQL logic error");
281        assert_eq!(error_string(SQLITE_BUSY), "database is locked");
282        assert_eq!(error_string(SQLITE_CONSTRAINT), "constraint failed");
283    }
284
285    #[test]
286    fn test_result_codes() {
287        // Verify result code constants match expected values
288        assert_eq!(SQLITE_OK, 0);
289        assert_eq!(SQLITE_ROW, 100);
290        assert_eq!(SQLITE_DONE, 101);
291    }
292}
sqlmodel_sqlite/ffi.rs

sqlmodel_sqlite/
ffi.rs
