Merge pull request #1597 from gwenn/trace_v2

Add bindings to sqlite3_trace_v2

libsqlite3-sys/bindgen-bindings/bindgen_3.14.0.rs

@@ -260,10 +260,10 @@ pub const SQLITE_FUNCTION: i32 = 31;
 pub const SQLITE_SAVEPOINT: i32 = 32;
 pub const SQLITE_COPY: i32 = 0;
 pub const SQLITE_RECURSIVE: i32 = 33;
-pub const SQLITE_TRACE_STMT: i32 = 1;
+pub const SQLITE_TRACE_STMT: ::std::os::raw::c_uint = 1;
-pub const SQLITE_TRACE_PROFILE: i32 = 2;
+pub const SQLITE_TRACE_PROFILE: ::std::os::raw::c_uint = 2;
-pub const SQLITE_TRACE_ROW: i32 = 4;
+pub const SQLITE_TRACE_ROW: ::std::os::raw::c_uint = 4;
-pub const SQLITE_TRACE_CLOSE: i32 = 8;
+pub const SQLITE_TRACE_CLOSE: ::std::os::raw::c_uint = 8;
 pub const SQLITE_LIMIT_LENGTH: i32 = 0;
 pub const SQLITE_LIMIT_SQL_LENGTH: i32 = 1;
 pub const SQLITE_LIMIT_COLUMN: i32 = 2;

libsqlite3-sys/bindgen-bindings/bindgen_3.14.0_ext.rs

@@ -237,10 +237,10 @@ pub const SQLITE_FUNCTION: i32 = 31;
 pub const SQLITE_SAVEPOINT: i32 = 32;
 pub const SQLITE_COPY: i32 = 0;
 pub const SQLITE_RECURSIVE: i32 = 33;
-pub const SQLITE_TRACE_STMT: i32 = 1;
+pub const SQLITE_TRACE_STMT: ::std::os::raw::c_uint = 1;
-pub const SQLITE_TRACE_PROFILE: i32 = 2;
+pub const SQLITE_TRACE_PROFILE: ::std::os::raw::c_uint = 2;
-pub const SQLITE_TRACE_ROW: i32 = 4;
+pub const SQLITE_TRACE_ROW: ::std::os::raw::c_uint = 4;
-pub const SQLITE_TRACE_CLOSE: i32 = 8;
+pub const SQLITE_TRACE_CLOSE: ::std::os::raw::c_uint = 8;
 pub const SQLITE_LIMIT_LENGTH: i32 = 0;
 pub const SQLITE_LIMIT_SQL_LENGTH: i32 = 1;
 pub const SQLITE_LIMIT_COLUMN: i32 = 2;

libsqlite3-sys/build.rs

@@ -507,6 +507,7 @@ mod bindings {
             if name == "SQLITE_SERIALIZE_NOCOPY"
                 || name.starts_with("SQLITE_DESERIALIZE_")
                 || name.starts_with("SQLITE_PREPARE_")
+                || name.starts_with("SQLITE_TRACE_")
             {
                 Some(IntKind::UInt)
             } else {

libsqlite3-sys/sqlcipher/bindgen_bundled_version.rs

@@ -319,10 +319,10 @@ pub const SQLITE_FUNCTION: i32 = 31;
 pub const SQLITE_SAVEPOINT: i32 = 32;
 pub const SQLITE_COPY: i32 = 0;
 pub const SQLITE_RECURSIVE: i32 = 33;
-pub const SQLITE_TRACE_STMT: i32 = 1;
+pub const SQLITE_TRACE_STMT: ::std::os::raw::c_uint = 1;
-pub const SQLITE_TRACE_PROFILE: i32 = 2;
+pub const SQLITE_TRACE_PROFILE: ::std::os::raw::c_uint = 2;
-pub const SQLITE_TRACE_ROW: i32 = 4;
+pub const SQLITE_TRACE_ROW: ::std::os::raw::c_uint = 4;
-pub const SQLITE_TRACE_CLOSE: i32 = 8;
+pub const SQLITE_TRACE_CLOSE: ::std::os::raw::c_uint = 8;
 pub const SQLITE_LIMIT_LENGTH: i32 = 0;
 pub const SQLITE_LIMIT_SQL_LENGTH: i32 = 1;
 pub const SQLITE_LIMIT_COLUMN: i32 = 2;

libsqlite3-sys/sqlite3/bindgen_bundled_version.rs

@@ -319,10 +319,10 @@ pub const SQLITE_FUNCTION: i32 = 31;
 pub const SQLITE_SAVEPOINT: i32 = 32;
 pub const SQLITE_COPY: i32 = 0;
 pub const SQLITE_RECURSIVE: i32 = 33;
-pub const SQLITE_TRACE_STMT: i32 = 1;
+pub const SQLITE_TRACE_STMT: ::std::os::raw::c_uint = 1;
-pub const SQLITE_TRACE_PROFILE: i32 = 2;
+pub const SQLITE_TRACE_PROFILE: ::std::os::raw::c_uint = 2;
-pub const SQLITE_TRACE_ROW: i32 = 4;
+pub const SQLITE_TRACE_ROW: ::std::os::raw::c_uint = 4;
-pub const SQLITE_TRACE_CLOSE: i32 = 8;
+pub const SQLITE_TRACE_CLOSE: ::std::os::raw::c_uint = 8;
 pub const SQLITE_LIMIT_LENGTH: i32 = 0;
 pub const SQLITE_LIMIT_SQL_LENGTH: i32 = 1;
 pub const SQLITE_LIMIT_COLUMN: i32 = 2;

libsqlite3-sys/sqlite3/bindgen_bundled_version_ext.rs

@@ -296,10 +296,10 @@ pub const SQLITE_FUNCTION: i32 = 31;
 pub const SQLITE_SAVEPOINT: i32 = 32;
 pub const SQLITE_COPY: i32 = 0;
 pub const SQLITE_RECURSIVE: i32 = 33;
-pub const SQLITE_TRACE_STMT: i32 = 1;
+pub const SQLITE_TRACE_STMT: ::std::os::raw::c_uint = 1;
-pub const SQLITE_TRACE_PROFILE: i32 = 2;
+pub const SQLITE_TRACE_PROFILE: ::std::os::raw::c_uint = 2;
-pub const SQLITE_TRACE_ROW: i32 = 4;
+pub const SQLITE_TRACE_ROW: ::std::os::raw::c_uint = 4;
-pub const SQLITE_TRACE_CLOSE: i32 = 8;
+pub const SQLITE_TRACE_CLOSE: ::std::os::raw::c_uint = 8;
 pub const SQLITE_LIMIT_LENGTH: i32 = 0;
 pub const SQLITE_LIMIT_SQL_LENGTH: i32 = 1;
 pub const SQLITE_LIMIT_COLUMN: i32 = 2;

src/hooks/mod.rs

@@ -452,7 +452,7 @@ pub enum CheckpointMode {
     FULL = ffi::SQLITE_CHECKPOINT_FULL,
     /// Like FULL but wait for readers
     RESTART = ffi::SQLITE_CHECKPOINT_RESTART,
-    /// Like RESTART but also truncate WA
+    /// Like RESTART but also truncate WAL
     TRUNCATE = ffi::SQLITE_CHECKPOINT_TRUNCATE,
 }
 

src/inner_connection.rs

@@ -309,7 +309,7 @@ impl InnerConnection {
 
     #[inline]
     pub fn is_autocommit(&self) -> bool {
-        unsafe { ffi::sqlite3_get_autocommit(self.db()) != 0 }
+        unsafe { get_autocommit(self.db()) }
     }
 
     pub fn is_busy(&self) -> bool {
@@ -393,6 +393,25 @@ impl InnerConnection {
     }
 }
 
+#[inline]
+pub(crate) unsafe fn get_autocommit(ptr: *mut ffi::sqlite3) -> bool {
+    ffi::sqlite3_get_autocommit(ptr) != 0
+}
+
+#[inline]
+pub(crate) unsafe fn db_filename(
+    ptr: *mut ffi::sqlite3,
+    db_name: crate::DatabaseName<'_>,
+) -> Option<&str> {
+    let db_name = db_name.as_cstr().unwrap();
+    let db_filename = ffi::sqlite3_db_filename(ptr, db_name.as_ptr());
+    if db_filename.is_null() {
+        None
+    } else {
+        CStr::from_ptr(db_filename).to_str().ok()
+    }
+}
+
 impl Drop for InnerConnection {
     #[expect(unused_must_use)]
     #[inline]

src/lib.rs

@@ -644,16 +644,7 @@ impl Connection {
     /// likely to be more robust.
     #[inline]
     pub fn path(&self) -> Option<&str> {
-        unsafe {
+        unsafe { crate::inner_connection::db_filename(self.handle(), DatabaseName::Main) }
-            let db = self.handle();
-            let db_name = DatabaseName::Main.as_cstr().unwrap();
-            let db_filename = ffi::sqlite3_db_filename(db, db_name.as_ptr());
-            if db_filename.is_null() {
-                None
-            } else {
-                CStr::from_ptr(db_filename).to_str().ok()
-            }
-        }
     }
 
     /// Attempts to free as much heap memory as possible from the database

src/raw_statement.rs

@@ -204,13 +204,12 @@ impl RawStatement {
 
     #[inline]
     pub(crate) fn expanded_sql(&self) -> Option<SqliteMallocString> {
-        unsafe { SqliteMallocString::from_raw(ffi::sqlite3_expanded_sql(self.ptr)) }
+        unsafe { expanded_sql(self.ptr) }
     }
 
     #[inline]
     pub fn get_status(&self, status: StatementStatus, reset: bool) -> i32 {
-        assert!(!self.ptr.is_null());
+        unsafe { stmt_status(self.ptr, status, reset) }
-        unsafe { ffi::sqlite3_stmt_status(self.ptr, status as i32, reset as i32) }
     }
 
     #[inline]
@@ -233,6 +232,20 @@ impl RawStatement {
     // TODO sqlite3_normalized_sql (https://sqlite.org/c3ref/expanded_sql.html) // 3.27.0 + SQLITE_ENABLE_NORMALIZE
 }
 
+#[inline]
+pub(crate) unsafe fn expanded_sql(ptr: *mut ffi::sqlite3_stmt) -> Option<SqliteMallocString> {
+    SqliteMallocString::from_raw(ffi::sqlite3_expanded_sql(ptr))
+}
+#[inline]
+pub(crate) unsafe fn stmt_status(
+    ptr: *mut ffi::sqlite3_stmt,
+    status: StatementStatus,
+    reset: bool,
+) -> i32 {
+    assert!(!ptr.is_null());
+    ffi::sqlite3_stmt_status(ptr, status as i32, reset as i32)
+}
+
 impl Drop for RawStatement {
     fn drop(&mut self) {
         self.finalize_();

src/trace.rs

@@ -1,14 +1,16 @@
 //! Tracing and profiling functions. Error and warning log.
 
+use std::borrow::Cow;
 use std::ffi::{CStr, CString};
+use std::marker::PhantomData;
 use std::mem;
-use std::os::raw::{c_char, c_int, c_void};
+use std::os::raw::{c_char, c_int, c_uint, c_void};
 use std::panic::catch_unwind;
 use std::ptr;
 use std::time::Duration;
 
 use super::ffi;
-use crate::Connection;
+use crate::{Connection, DatabaseName, StatementStatus};
 
 /// Set up the process-wide SQLite error logging callback.
 ///
@@ -61,6 +63,84 @@ pub fn log(err_code: c_int, msg: &str) {
     }
 }
 
+bitflags::bitflags! {
+    /// Trace event codes
+    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+    #[non_exhaustive]
+    #[repr(C)]
+    pub struct TraceEventCodes: ::std::os::raw::c_uint {
+        /// when a prepared statement first begins running and possibly at other times during the execution
+        /// of the prepared statement, such as at the start of each trigger subprogram
+        const SQLITE_TRACE_STMT = ffi::SQLITE_TRACE_STMT;
+        /// when the statement finishes
+        const SQLITE_TRACE_PROFILE = ffi::SQLITE_TRACE_PROFILE;
+        /// whenever a prepared statement generates a single row of result
+        const SQLITE_TRACE_ROW = ffi::SQLITE_TRACE_ROW;
+        /// when a database connection closes
+        const SQLITE_TRACE_CLOSE = ffi::SQLITE_TRACE_CLOSE;
+    }
+}
+
+/// Trace event
+#[non_exhaustive]
+pub enum TraceEvent<'s> {
+    /// when a prepared statement first begins running and possibly at other times during the execution
+    /// of the prepared statement, such as at the start of each trigger subprogram
+    Stmt(StmtRef<'s>, &'s str),
+    /// when the statement finishes
+    Profile(StmtRef<'s>, Duration),
+    /// whenever a prepared statement generates a single row of result
+    Row(StmtRef<'s>),
+    /// when a database connection closes
+    Close(ConnRef<'s>),
+}
+
+/// Statement reference
+pub struct StmtRef<'s> {
+    ptr: *mut ffi::sqlite3_stmt,
+    phantom: PhantomData<&'s ()>,
+}
+
+impl StmtRef<'_> {
+    fn new(ptr: *mut ffi::sqlite3_stmt) -> Self {
+        StmtRef {
+            ptr,
+            phantom: PhantomData,
+        }
+    }
+    /// SQL text
+    pub fn sql(&self) -> Cow<'_, str> {
+        unsafe { CStr::from_ptr(ffi::sqlite3_sql(self.ptr)).to_string_lossy() }
+    }
+    /// Expanded SQL text
+    pub fn expanded_sql(&self) -> Option<String> {
+        unsafe {
+            crate::raw_statement::expanded_sql(self.ptr).map(|s| s.to_string_lossy().to_string())
+        }
+    }
+    /// Get the value for one of the status counters for this statement.
+    pub fn get_status(&self, status: StatementStatus) -> i32 {
+        unsafe { crate::raw_statement::stmt_status(self.ptr, status, false) }
+    }
+}
+
+/// Connection reference
+pub struct ConnRef<'s> {
+    ptr: *mut ffi::sqlite3,
+    phantom: PhantomData<&'s ()>,
+}
+
+impl ConnRef<'_> {
+    /// Test for auto-commit mode.
+    pub fn is_autocommit(&self) -> bool {
+        unsafe { crate::inner_connection::get_autocommit(self.ptr) }
+    }
+    /// the path to the database file, if one exists and is known.
+    pub fn db_filename(&self) -> Option<&str> {
+        unsafe { crate::inner_connection::db_filename(self.ptr, DatabaseName::Main) }
+    }
+}
+
 impl Connection {
     /// Register or clear a callback function that can be
     /// used for tracing the execution of SQL statements.
@@ -68,6 +148,7 @@ impl Connection {
     /// Prepared statement placeholders are replaced/logged with their assigned
     /// values. There can only be a single tracer defined for each database
     /// connection. Setting a new tracer clears the old one.
+    #[deprecated(since = "0.33.0", note = "use trace_v2 instead")]
     pub fn trace(&mut self, trace_fn: Option<fn(&str)>) {
         unsafe extern "C" fn trace_callback(p_arg: *mut c_void, z_sql: *const c_char) {
             let trace_fn: fn(&str) = mem::transmute(p_arg);
@@ -91,6 +172,7 @@ impl Connection {
     ///
     /// There can only be a single profiler defined for each database
     /// connection. Setting a new profiler clears the old one.
+    #[deprecated(since = "0.33.0", note = "use trace_v2 instead")]
     pub fn profile(&mut self, profile_fn: Option<fn(&str, Duration)>) {
         unsafe extern "C" fn profile_callback(
             p_arg: *mut c_void,
@@ -99,12 +181,8 @@ impl Connection {
         ) {
             let profile_fn: fn(&str, Duration) = mem::transmute(p_arg);
             let s = CStr::from_ptr(z_sql).to_string_lossy();
-            const NANOS_PER_SEC: u64 = 1_000_000_000;
 
-            let duration = Duration::new(
+            let duration = Duration::from_nanos(nanoseconds);
-                nanoseconds / NANOS_PER_SEC,
-                (nanoseconds % NANOS_PER_SEC) as u32,
-            );
             drop(catch_unwind(|| profile_fn(&s, duration)));
         }
 
@@ -117,7 +195,54 @@ impl Connection {
         };
     }
 
-    // TODO sqlite3_trace_v2 (https://sqlite.org/c3ref/trace_v2.html) // 3.14.0, #977
+    /// Register or clear a trace callback function
+    pub fn trace_v2(&self, mask: TraceEventCodes, trace_fn: Option<fn(TraceEvent<'_>)>) {
+        unsafe extern "C" fn trace_callback(
+            evt: c_uint,
+            ctx: *mut c_void,
+            p: *mut c_void,
+            x: *mut c_void,
+        ) -> c_int {
+            let trace_fn: fn(TraceEvent<'_>) = mem::transmute(ctx);
+            drop(catch_unwind(|| match evt {
+                ffi::SQLITE_TRACE_STMT => {
+                    let str = CStr::from_ptr(x as *const c_char).to_string_lossy();
+                    trace_fn(TraceEvent::Stmt(
+                        StmtRef::new(p as *mut ffi::sqlite3_stmt),
+                        &str,
+                    ))
+                }
+                ffi::SQLITE_TRACE_PROFILE => {
+                    let ns = *(x as *const i64);
+                    trace_fn(TraceEvent::Profile(
+                        StmtRef::new(p as *mut ffi::sqlite3_stmt),
+                        Duration::from_nanos(u64::try_from(ns).unwrap_or_default()),
+                    ))
+                }
+                ffi::SQLITE_TRACE_ROW => {
+                    trace_fn(TraceEvent::Row(StmtRef::new(p as *mut ffi::sqlite3_stmt)))
+                }
+                ffi::SQLITE_TRACE_CLOSE => trace_fn(TraceEvent::Close(ConnRef {
+                    ptr: p as *mut ffi::sqlite3,
+                    phantom: PhantomData,
+                })),
+                _ => {}
+            }));
+            // The integer return value from the callback is currently ignored, though this may change in future releases.
+            // Callback implementations should return zero to ensure future compatibility.
+            ffi::SQLITE_OK
+        }
+        let c = self.db.borrow_mut();
+        if let Some(f) = trace_fn {
+            unsafe {
+                ffi::sqlite3_trace_v2(c.db(), mask.bits(), Some(trace_callback), f as *mut c_void);
+            }
+        } else {
+            unsafe {
+                ffi::sqlite3_trace_v2(c.db(), 0, None, ptr::null_mut());
+            }
+        }
+    }
 }
 
 #[cfg(test)]
@@ -128,6 +253,7 @@ mod test {
     use crate::{Connection, Result};
 
     #[test]
+    #[allow(deprecated)]
     fn test_trace() -> Result<()> {
         static TRACED_STMTS: LazyLock<Mutex<Vec<String>>> =
             LazyLock::new(|| Mutex::new(Vec::new()));
@@ -156,6 +282,7 @@ mod test {
     }
 
     #[test]
+    #[allow(deprecated)]
     fn test_profile() -> Result<()> {
         static PROFILED: LazyLock<Mutex<Vec<(String, Duration)>>> =
             LazyLock::new(|| Mutex::new(Vec::new()));
@@ -175,4 +302,39 @@ mod test {
         assert_eq!(profiled[0].0, "PRAGMA application_id = 1");
         Ok(())
     }
+
+    #[test]
+    pub fn trace_v2() -> Result<()> {
+        use super::{TraceEvent, TraceEventCodes};
+        use std::borrow::Borrow;
+        use std::cmp::Ordering;
+
+        let db = Connection::open_in_memory()?;
+        db.trace_v2(
+            TraceEventCodes::all(),
+            Some(|e| match e {
+                TraceEvent::Stmt(s, sql) => {
+                    assert_eq!(s.sql(), sql);
+                }
+                TraceEvent::Profile(s, d) => {
+                    assert_eq!(s.get_status(crate::StatementStatus::Sort), 0);
+                    assert_eq!(d.cmp(&Duration::ZERO), Ordering::Greater)
+                }
+                TraceEvent::Row(s) => {
+                    assert_eq!(s.expanded_sql().as_deref(), Some(s.sql().borrow()));
+                }
+                TraceEvent::Close(db) => {
+                    assert!(db.is_autocommit());
+                    assert!(db.db_filename().is_none());
+                }
+            }),
+        );
+
+        db.one_column::<u32>("PRAGMA user_version")?;
+        drop(db);
+
+        let db = Connection::open_in_memory()?;
+        db.trace_v2(TraceEventCodes::empty(), None);
+        Ok(())
+    }
 }