diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md index aa0ffeb..39264b7 100644 --- a/CONTRIBUTORS.md +++ b/CONTRIBUTORS.md @@ -9,4 +9,5 @@ rusqlite contributors (sorted alphabetically) * [Patrick Fernie](https://github.com/pfernie) * [Steve Klabnik](https://github.com/steveklabnik) * [krdln](https://github.com/krdln) +* [Ben Striegel](https://github.com/bstrie) * [Andrew Straw](https://github.com/astraw) diff --git a/Cargo.toml b/Cargo.toml index 1efbe76..673c8ea 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -14,6 +14,7 @@ name = "rusqlite" [features] load_extension = ["libsqlite3-sys/load_extension"] +trace = [] [dependencies] time = "~0.1.0" @@ -22,7 +23,12 @@ libc = "~0.2" [dev-dependencies] tempdir = "~0.3.4" +lazy_static = "~0.1" [dependencies.libsqlite3-sys] path = "libsqlite3-sys" version = "0.2.0" + +[[test]] +name = "config_log" +harness = false diff --git a/Changelog.md b/Changelog.md index 4b341b4..4efd2e8 100644 --- a/Changelog.md +++ b/Changelog.md @@ -1,10 +1,12 @@ -# Version UPCOMDING (TBD) +# Version UPCOMING (TBD) +* Adds `trace` feature that allows the use of SQLite's logging, tracing, and profiling hooks. * Slight change to the closure types passed to `query_map` and `query_and_then`: * Remove the `'static` requirement on the closure's output type. * Give the closure a `&SqliteRow` instead of a `SqliteRow`. * When building, the environment variable `SQLITE3_LIB_DIR` now takes precedence over pkg-config. * If `pkg-config` is not available, we will try to find `libsqlite3` in `/usr/lib`. +* Add more documentation for failure modes of functions that return `SqliteResult`s. # Version 0.4.0 (2015-11-03) diff --git a/libsqlite3-sys/src/lib.rs b/libsqlite3-sys/src/lib.rs index 5d37276..51f33c5 100644 --- a/libsqlite3-sys/src/lib.rs +++ b/libsqlite3-sys/src/lib.rs @@ -92,3 +92,5 @@ pub fn code_to_str(code: c_int) -> &'static str { _ => "Unknown error code", } } + +pub const SQLITE_CONFIG_LOG : c_int = 16; diff --git a/src/lib.rs b/src/lib.rs index cae3c59..6332b45 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -53,6 +53,7 @@ extern crate libc; extern crate libsqlite3_sys as ffi; #[macro_use] extern crate bitflags; +#[cfg(test)] #[macro_use] extern crate lazy_static; use std::default::Default; use std::convert; @@ -80,6 +81,7 @@ pub use transaction::{SqliteTransactionBehavior, pub mod types; mod transaction; #[cfg(feature = "load_extension")] mod load_extension_guard; +#[cfg(feature = "trace")] pub mod trace; /// A typedef of the result returned by many methods. pub type SqliteResult = Result; @@ -128,28 +130,19 @@ impl SqliteError { fn str_to_cstring(s: &str) -> SqliteResult { CString::new(s).map_err(|_| SqliteError{ code: ffi::SQLITE_MISUSE, - message: "Could not convert path to C-combatible string".to_string() + message: format!("Could not convert string {} to C-combatible string", s), }) } fn path_to_cstring(p: &Path) -> SqliteResult { let s = try!(p.to_str().ok_or(SqliteError{ code: ffi::SQLITE_MISUSE, - message: "Could not convert path to UTF-8 string".to_string() + message: format!("Could not convert path {} to UTF-8 string", p.to_string_lossy()), })); str_to_cstring(s) } /// A connection to a SQLite database. -/// -/// ## Warning -/// -/// Note that despite the fact that most `SqliteConnection` methods take an immutable reference to -/// `self`, `SqliteConnection` is NOT threadsafe, and using it from multiple threads may result in -/// runtime panics or data races. The SQLite connection handle has at least two pieces of internal -/// state (the last insertion ID and the last error message) that rusqlite uses, but wrapping these -/// APIs in a safe way from Rust would be too restrictive (for example, you would not be able to -/// prepare multiple statements at the same time). pub struct SqliteConnection { db: RefCell, path: Option, @@ -162,12 +155,21 @@ impl SqliteConnection { /// /// `SqliteConnection::open(path)` is equivalent to `SqliteConnection::open_with_flags(path, /// SQLITE_OPEN_READ_WRITE | SQLITE_OPEN_CREATE)`. + /// + /// # Failure + /// + /// Will return `Err` if `path` cannot be converted to a C-compatible string or if the + /// underlying SQLite open call fails. pub fn open>(path: P) -> SqliteResult { let flags = Default::default(); SqliteConnection::open_with_flags(path, flags) } /// Open a new connection to an in-memory SQLite database. + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite open call fails. pub fn open_in_memory() -> SqliteResult { let flags = Default::default(); SqliteConnection::open_in_memory_with_flags(flags) @@ -177,6 +179,11 @@ impl SqliteConnection { /// /// Database Connection](http://www.sqlite.org/c3ref/open.html) for a description of valid /// flag combinations. + /// + /// # Failure + /// + /// Will return `Err` if `path` cannot be converted to a C-compatible string or if the + /// underlying SQLite open call fails. pub fn open_with_flags>(path: P, flags: SqliteOpenFlags) -> SqliteResult { let c_path = try!(path_to_cstring(path.as_ref())); @@ -189,6 +196,10 @@ impl SqliteConnection { /// /// Database Connection](http://www.sqlite.org/c3ref/open.html) for a description of valid /// flag combinations. + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite open call fails. pub fn open_in_memory_with_flags(flags: SqliteOpenFlags) -> SqliteResult { let c_memory = try!(str_to_cstring(":memory:")); InnerSqliteConnection::open_with_flags(&c_memory, flags).map(|db| { @@ -216,6 +227,10 @@ impl SqliteConnection { /// tx.commit() /// } /// ``` + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite call fails. pub fn transaction<'a>(&'a self) -> SqliteResult> { SqliteTransaction::new(self, SqliteTransactionDeferred) } @@ -223,6 +238,10 @@ impl SqliteConnection { /// Begin a new transaction with a specified behavior. /// /// See `transaction`. + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite call fails. pub fn transaction_with_behavior<'a>(&'a self, behavior: SqliteTransactionBehavior) -> SqliteResult> { SqliteTransaction::new(self, behavior) @@ -243,6 +262,11 @@ impl SqliteConnection { /// COMMIT;") /// } /// ``` + /// + /// # Failure + /// + /// Will return `Err` if `sql` cannot be converted to a C-compatible string or if the + /// underlying SQLite call fails. pub fn execute_batch(&self, sql: &str) -> SqliteResult<()> { self.db.borrow_mut().execute_batch(sql) } @@ -263,6 +287,11 @@ impl SqliteConnection { /// } /// } /// ``` + /// + /// # Failure + /// + /// Will return `Err` if `sql` cannot be converted to a C-compatible string or if the + /// underlying SQLite call fails. pub fn execute(&self, sql: &str, params: &[&ToSql]) -> SqliteResult { self.prepare(sql).and_then(|mut stmt| stmt.execute(params)) } @@ -289,6 +318,11 @@ impl SqliteConnection { /// ``` /// /// If the query returns more than one row, all rows except the first are ignored. + /// + /// # Failure + /// + /// Will return `Err` if `sql` cannot be converted to a C-compatible string or if the + /// underlying SQLite call fails. pub fn query_row(&self, sql: &str, params: &[&ToSql], f: F) -> SqliteResult where F: FnOnce(SqliteRow) -> T { let mut stmt = try!(self.prepare(sql)); @@ -319,6 +353,11 @@ impl SqliteConnection { /// ``` /// /// If the query returns more than one row, all rows except the first are ignored. + /// + /// # Failure + /// + /// Will return `Err` if `sql` cannot be converted to a C-compatible string or if the + /// underlying SQLite call fails. pub fn query_row_and_then(&self, sql: &str, params: &[&ToSql], f: F) -> Result where F: FnOnce(SqliteRow) -> Result, E: convert::From { @@ -371,6 +410,11 @@ impl SqliteConnection { /// Ok(()) /// } /// ``` + /// + /// # Failure + /// + /// Will return `Err` if `sql` cannot be converted to a C-compatible string or if the + /// underlying SQLite call fails. pub fn prepare<'a>(&'a self, sql: &str) -> SqliteResult> { self.db.borrow_mut().prepare(self, sql) } @@ -379,6 +423,10 @@ impl SqliteConnection { /// /// This is functionally equivalent to the `Drop` implementation for `SqliteConnection` except /// that it returns any error encountered to the caller. + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite call fails. pub fn close(self) -> SqliteResult<()> { let mut db = self.db.borrow_mut(); db.close() @@ -398,6 +446,10 @@ impl SqliteConnection { /// conn.load_extension_disable() /// } /// ``` + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite call fails. #[cfg(feature = "load_extension")] pub fn load_extension_enable(&self) -> SqliteResult<()> { self.db.borrow_mut().enable_load_extension(1) @@ -406,6 +458,10 @@ impl SqliteConnection { /// Disable loading of SQLite extensions. /// /// See `load_extension_enable` for an example. + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite call fails. #[cfg(feature = "load_extension")] pub fn load_extension_disable(&self) -> SqliteResult<()> { self.db.borrow_mut().enable_load_extension(0) @@ -428,6 +484,10 @@ impl SqliteConnection { /// /// conn.load_extension("my_sqlite_extension", None) /// } + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite call fails. #[cfg(feature = "load_extension")] pub fn load_extension>(&self, dylib_path: P, entry_point: Option<&str>) -> SqliteResult<()> { self.db.borrow_mut().load_extension(dylib_path, entry_point) @@ -653,6 +713,11 @@ impl<'conn> SqliteStatement<'conn> { /// Ok(()) /// } /// ``` + /// + /// # Failure + /// + /// Will return `Err` if binding parameters fails, the executed statement returns rows (in + /// which case `query` should be used instead), or the underling SQLite call fails. pub fn execute(&mut self, params: &[&ToSql]) -> SqliteResult { unsafe { try!(self.bind_parameters(params)); @@ -694,6 +759,10 @@ impl<'conn> SqliteStatement<'conn> { /// Ok(names) /// } /// ``` + /// + /// # Failure + /// + /// Will return `Err` if binding parameters fails. pub fn query<'a>(&'a mut self, params: &[&ToSql]) -> SqliteResult> { self.reset_if_needed(); @@ -710,6 +779,10 @@ impl<'conn> SqliteStatement<'conn> { /// /// Unlike the iterator produced by `query`, the returned iterator does not expose the possibility /// for accessing stale rows. + /// + /// # Failure + /// + /// Will return `Err` if binding parameters fails. pub fn query_map<'a, T, F>(&'a mut self, params: &[&ToSql], f: F) -> SqliteResult> where F: FnMut(&SqliteRow) -> T { @@ -727,6 +800,10 @@ impl<'conn> SqliteStatement<'conn> { /// /// Unlike the iterator produced by `query`, the returned iterator does not expose the possibility /// for accessing stale rows. + /// + /// # Failure + /// + /// Will return `Err` if binding parameters fails. pub fn query_and_then<'a, T, E, F>(&'a mut self, params: &[&ToSql], f: F) -> SqliteResult> where E: convert::From, @@ -743,6 +820,10 @@ impl<'conn> SqliteStatement<'conn> { /// /// Functionally equivalent to the `Drop` implementation, but allows callers to see any errors /// that occur. + /// + /// # Failure + /// + /// Will return `Err` if the underlying SQLite call fails. pub fn finalize(mut self) -> SqliteResult<()> { self.finalize_() } diff --git a/src/trace.rs b/src/trace.rs new file mode 100644 index 0000000..4296ddc --- /dev/null +++ b/src/trace.rs @@ -0,0 +1,162 @@ +//! Tracing and profiling functions. Error and warning log. + +use libc::{c_char, c_int, c_void}; +use std::ffi::{CStr, CString}; +use std::mem; +use std::ptr; +use std::str; +use std::time::Duration; + +use super::ffi; +use {SqliteError, SqliteResult, SqliteConnection}; + +/// Set up the process-wide SQLite error logging callback. +/// This function is marked unsafe for two reasons: +/// +/// * The function is not threadsafe. No other SQLite calls may be made while +/// `config_log` is running, and multiple threads may not call `config_log` +/// simultaneously. +/// * The provided `callback` itself function has two requirements: +/// * It must not invoke any SQLite calls. +/// * It must be threadsafe if SQLite is used in a multithreaded way. +/// +/// cf [The Error And Warning Log](http://sqlite.org/errlog.html). +pub unsafe fn config_log(callback: Option) -> SqliteResult<()> { + extern "C" fn log_callback(p_arg: *mut c_void, err: c_int, msg: *const c_char) { + let c_slice = unsafe { CStr::from_ptr(msg).to_bytes() }; + let callback: fn(c_int, &str) = unsafe { mem::transmute(p_arg) }; + + if let Ok(s) = str::from_utf8(c_slice) { + callback(err, s); + } + } + + let rc = match callback { + Some(f) => { + let p_arg: *mut c_void = mem::transmute(f); + ffi::sqlite3_config(ffi::SQLITE_CONFIG_LOG, Some(log_callback), p_arg) + }, + None => { + let nullptr: *mut c_void = ptr::null_mut(); + ffi::sqlite3_config(ffi::SQLITE_CONFIG_LOG, nullptr, nullptr) + } + }; + + if rc != ffi::SQLITE_OK { + return Err(SqliteError{ code: rc, message: "sqlite3_config(SQLITE_CONFIG_LOG, ...)".to_string() }); + } + + Ok(()) +} + +/// Write a message into the error log established by `config_log`. +pub fn log(err_code: c_int, msg: &str) { + let msg = CString::new(msg).expect("SQLite log messages cannot contain embedded zeroes"); + unsafe { + ffi::sqlite3_log(err_code, msg.as_ptr()); + } +} + +impl SqliteConnection { + /// Register or clear a callback function that can be used for tracing the execution of SQL statements. + /// + /// 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. + pub fn trace(&mut self, trace_fn: Option) { + extern "C" fn trace_callback (p_arg: *mut c_void, z_sql: *const c_char) { + let trace_fn: fn(&str) = unsafe { mem::transmute(p_arg) }; + let c_slice = unsafe { CStr::from_ptr(z_sql).to_bytes() }; + if let Ok(s) = str::from_utf8(c_slice) { + trace_fn(s); + } + } + + let c = self.db.borrow_mut(); + match trace_fn { + Some(f) => unsafe { ffi::sqlite3_trace(c.db(), Some(trace_callback), mem::transmute(f)); }, + None => unsafe { ffi::sqlite3_trace(c.db(), None, ptr::null_mut()); }, + } + } + + /// Register or clear a callback function that can be used for profiling the execution of SQL statements. + /// + /// There can only be a single profiler defined for each database connection. + /// Setting a new profiler clears the old one. + pub fn profile(&mut self, profile_fn: Option) { + extern "C" fn profile_callback(p_arg: *mut c_void, z_sql: *const c_char, nanoseconds: u64) { + let profile_fn: fn(&str, Duration) = unsafe { mem::transmute(p_arg) }; + let c_slice = unsafe { CStr::from_ptr(z_sql).to_bytes() }; + if let Ok(s) = str::from_utf8(c_slice) { + const NANOS_PER_SEC: u64 = 1_000_000_000; + + let duration = Duration::new(nanoseconds / NANOS_PER_SEC, + (nanoseconds % NANOS_PER_SEC) as u32); + profile_fn(s, duration); + } + } + + let c = self.db.borrow_mut(); + match profile_fn { + Some(f) => unsafe { ffi::sqlite3_profile(c.db(), Some(profile_callback), mem::transmute(f)) }, + None => unsafe { ffi::sqlite3_profile(c.db(), None, ptr::null_mut()) }, + }; + } +} + +#[cfg(test)] +mod test { + use std::sync::Mutex; + use std::time::Duration; + + use SqliteConnection; + + #[test] + fn test_trace() { + lazy_static! { + static ref TRACED_STMTS: Mutex> = Mutex::new(Vec::new()); + } + fn tracer(s: &str) { + let mut traced_stmts = TRACED_STMTS.lock().unwrap(); + traced_stmts.push(s.to_owned()); + } + + let mut db = SqliteConnection::open_in_memory().unwrap(); + db.trace(Some(tracer)); + { + let _ = db.query_row("SELECT ?", &[&1i32], |_| {}); + let _ = db.query_row("SELECT ?", &[&"hello"], |_| {}); + } + db.trace(None); + { + let _ = db.query_row("SELECT ?", &[&2i32], |_| {}); + let _ = db.query_row("SELECT ?", &[&"goodbye"], |_| {}); + } + + let traced_stmts = TRACED_STMTS.lock().unwrap(); + assert_eq!(traced_stmts.len(), 2); + assert_eq!(traced_stmts[0], "SELECT 1"); + assert_eq!(traced_stmts[1], "SELECT 'hello'"); + } + + #[test] + fn test_profile() { + lazy_static! { + static ref PROFILED: Mutex> = Mutex::new(Vec::new()); + } + fn profiler(s: &str, d: Duration) { + let mut profiled = PROFILED.lock().unwrap(); + profiled.push((s.to_owned(), d)); + } + + let mut db = SqliteConnection::open_in_memory().unwrap(); + db.profile(Some(profiler)); + db.execute_batch("PRAGMA application_id = 1").unwrap(); + db.profile(None); + db.execute_batch("PRAGMA application_id = 2").unwrap(); + + let profiled = PROFILED.lock().unwrap(); + assert_eq!(profiled.len(), 1); + assert_eq!(profiled[0].0, "PRAGMA application_id = 1"); + } +} diff --git a/tests/config_log.rs b/tests/config_log.rs new file mode 100644 index 0000000..e0167bd --- /dev/null +++ b/tests/config_log.rs @@ -0,0 +1,36 @@ +//! This file contains unit tests for rusqlite::trace::config_log. This function affects +//! SQLite process-wide and so is not safe to run as a normal #[test] in the library. + +#[macro_use] extern crate lazy_static; +extern crate libc; +extern crate rusqlite; + +#[cfg(feature = "trace")] +fn main() { + use libc::c_int; + use std::sync::Mutex; + + lazy_static! { + static ref LOGS_RECEIVED: Mutex> = Mutex::new(Vec::new()); + } + + fn log_handler(err: c_int, message: &str) { + let mut logs_received = LOGS_RECEIVED.lock().unwrap(); + logs_received.push((err, message.to_owned())); + } + + use rusqlite::trace; + + unsafe { trace::config_log(Some(log_handler)) }.unwrap(); + trace::log(10, "First message from rusqlite"); + unsafe { trace::config_log(None) }.unwrap(); + trace::log(11, "Second message from rusqlite"); + + let logs_received = LOGS_RECEIVED.lock().unwrap(); + assert_eq!(logs_received.len(), 1); + assert_eq!(logs_received[0].0, 10); + assert_eq!(logs_received[0].1, "First message from rusqlite"); +} + +#[cfg(not(feature = "trace"))] +fn main() {}