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// Native SQLite linkage is intentionally owned by the `libsqlite3-sys`
100// dependency. Its bundled feature compiles the vendored amalgamation and emits
101// the correct static `cargo:rustc-link-*` metadata; lib.rs keeps that dependency
102// linked even though these bindings are declared manually here.
103unsafe extern "C" {
104    // Connection management
105    pub fn sqlite3_open(filename: *const c_char, ppDb: *mut *mut sqlite3) -> c_int;
106
107    pub fn sqlite3_open_v2(
108        filename: *const c_char,
109        ppDb: *mut *mut sqlite3,
110        flags: c_int,
111        zVfs: *const c_char,
112    ) -> c_int;
113
114    pub fn sqlite3_close(db: *mut sqlite3) -> c_int;
115    pub fn sqlite3_close_v2(db: *mut sqlite3) -> c_int;
116
117    // Backup API
118    pub fn sqlite3_backup_init(
119        pDest: *mut sqlite3,
120        zDestName: *const c_char,
121        pSource: *mut sqlite3,
122        zSourceName: *const c_char,
123    ) -> *mut sqlite3_backup;
124    pub fn sqlite3_backup_step(p: *mut sqlite3_backup, nPage: c_int) -> c_int;
125    pub fn sqlite3_backup_finish(p: *mut sqlite3_backup) -> c_int;
126    pub fn sqlite3_backup_remaining(p: *mut sqlite3_backup) -> c_int;
127    pub fn sqlite3_backup_pagecount(p: *mut sqlite3_backup) -> c_int;
128
129    // Error handling
130    pub fn sqlite3_errmsg(db: *mut sqlite3) -> *const c_char;
131    pub fn sqlite3_errcode(db: *mut sqlite3) -> c_int;
132    pub fn sqlite3_extended_errcode(db: *mut sqlite3) -> c_int;
133    pub fn sqlite3_errstr(errcode: c_int) -> *const c_char;
134
135    // Statement preparation
136    pub fn sqlite3_prepare_v2(
137        db: *mut sqlite3,
138        zSql: *const c_char,
139        nByte: c_int,
140        ppStmt: *mut *mut sqlite3_stmt,
141        pzTail: *mut *const c_char,
142    ) -> c_int;
143
144    pub fn sqlite3_finalize(pStmt: *mut sqlite3_stmt) -> c_int;
145    pub fn sqlite3_reset(pStmt: *mut sqlite3_stmt) -> c_int;
146    pub fn sqlite3_clear_bindings(pStmt: *mut sqlite3_stmt) -> c_int;
147
148    // Parameter binding
149    pub fn sqlite3_bind_null(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
150
151    pub fn sqlite3_bind_int(pStmt: *mut sqlite3_stmt, index: c_int, value: c_int) -> c_int;
152
153    pub fn sqlite3_bind_int64(pStmt: *mut sqlite3_stmt, index: c_int, value: i64) -> c_int;
154
155    pub fn sqlite3_bind_double(pStmt: *mut sqlite3_stmt, index: c_int, value: c_double) -> c_int;
156
157    pub fn sqlite3_bind_text(
158        pStmt: *mut sqlite3_stmt,
159        index: c_int,
160        value: *const c_char,
161        nBytes: c_int,
162        destructor: sqlite3_destructor_type,
163    ) -> c_int;
164
165    pub fn sqlite3_bind_blob(
166        pStmt: *mut sqlite3_stmt,
167        index: c_int,
168        value: *const c_void,
169        nBytes: c_int,
170        destructor: sqlite3_destructor_type,
171    ) -> c_int;
172
173    pub fn sqlite3_bind_parameter_count(pStmt: *mut sqlite3_stmt) -> c_int;
174    pub fn sqlite3_bind_parameter_index(pStmt: *mut sqlite3_stmt, name: *const c_char) -> c_int;
175    pub fn sqlite3_bind_parameter_name(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
176
177    // Stepping through results
178    pub fn sqlite3_step(pStmt: *mut sqlite3_stmt) -> c_int;
179
180    // Result column information
181    pub fn sqlite3_column_count(pStmt: *mut sqlite3_stmt) -> c_int;
182    pub fn sqlite3_column_name(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
183    pub fn sqlite3_column_type(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
184    pub fn sqlite3_column_decltype(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
185
186    // Result column values
187    pub fn sqlite3_column_int(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
188    pub fn sqlite3_column_int64(pStmt: *mut sqlite3_stmt, index: c_int) -> i64;
189    pub fn sqlite3_column_double(pStmt: *mut sqlite3_stmt, index: c_int) -> c_double;
190    pub fn sqlite3_column_text(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_char;
191    pub fn sqlite3_column_blob(pStmt: *mut sqlite3_stmt, index: c_int) -> *const c_void;
192    pub fn sqlite3_column_bytes(pStmt: *mut sqlite3_stmt, index: c_int) -> c_int;
193
194    // Execution helpers
195    pub fn sqlite3_exec(
196        db: *mut sqlite3,
197        sql: *const c_char,
198        callback: Option<
199            unsafe extern "C" fn(*mut c_void, c_int, *mut *mut c_char, *mut *mut c_char) -> c_int,
200        >,
201        arg: *mut c_void,
202        errmsg: *mut *mut c_char,
203    ) -> c_int;
204
205    pub fn sqlite3_free(ptr: *mut c_void);
206
207    // Metadata
208    pub fn sqlite3_changes(db: *mut sqlite3) -> c_int;
209    pub fn sqlite3_total_changes(db: *mut sqlite3) -> c_int;
210    pub fn sqlite3_last_insert_rowid(db: *mut sqlite3) -> i64;
211
212    // Configuration
213    pub fn sqlite3_busy_timeout(db: *mut sqlite3, ms: c_int) -> c_int;
214
215    // Version info
216    pub fn sqlite3_libversion() -> *const c_char;
217    pub fn sqlite3_libversion_number() -> c_int;
218}
219
220/// Get the SQLite library version as a string.
221pub fn version() -> &'static str {
222    // SAFETY: sqlite3_libversion returns a static string
223    unsafe {
224        let ptr = sqlite3_libversion();
225        std::ffi::CStr::from_ptr(ptr).to_str().unwrap_or("unknown")
226    }
227}
228
229/// Get the SQLite library version as a number.
230pub fn version_number() -> i32 {
231    // SAFETY: sqlite3_libversion_number is always safe to call
232    unsafe { sqlite3_libversion_number() }
233}
234
235/// Convert an SQLite result code to a human-readable string.
236pub fn error_string(code: c_int) -> &'static str {
237    // SAFETY: sqlite3_errstr returns a static string
238    unsafe {
239        let ptr = sqlite3_errstr(code);
240        std::ffi::CStr::from_ptr(ptr)
241            .to_str()
242            .unwrap_or("unknown error")
243    }
244}
245
246#[cfg(test)]
247mod tests {
248    use super::*;
249
250    #[test]
251    fn test_version() {
252        let v = version();
253        assert!(!v.is_empty());
254        // SQLite version should start with 3.
255        assert!(v.starts_with('3'));
256    }
257
258    #[test]
259    fn test_version_number() {
260        let v = version_number();
261        // SQLite 3.x.x version numbers are in the form 3XXYYZZ
262        // e.g., 3.45.0 = 3045000
263        assert!(v >= 3_000_000);
264    }
265
266    #[test]
267    fn test_error_string() {
268        assert_eq!(error_string(SQLITE_OK), "not an error");
269        assert_eq!(error_string(SQLITE_ERROR), "SQL logic error");
270        assert_eq!(error_string(SQLITE_BUSY), "database is locked");
271        assert_eq!(error_string(SQLITE_CONSTRAINT), "constraint failed");
272    }
273
274    #[test]
275    fn test_result_codes() {
276        // Verify result code constants match expected values
277        assert_eq!(SQLITE_OK, 0);
278        assert_eq!(SQLITE_ROW, 100);
279        assert_eq!(SQLITE_DONE, 101);
280    }
281}
sqlmodel_sqlite/ffi.rs

sqlmodel_sqlite/
ffi.rs
