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

sqlmodel_sqlite/
ffi.rs
