Rusqlite

Rusqlite is an ergonomic wrapper for using SQLite from Rust. It attempts to expose
an interface similar to rust-postgres.

use rusqlite::{params, Connection, Result};
use time::Timespec;

#[derive(Debug)]
struct Person {
    id: i32,
    name: String,
    time_created: Timespec,
    data: Option<Vec<u8>>,
}

fn main() -> Result<()> {
    let conn = Connection::open_in_memory()?;

    conn.execute(
        "CREATE TABLE person (
                  id              INTEGER PRIMARY KEY,
                  name            TEXT NOT NULL,
                  time_created    TEXT NOT NULL,
                  data            BLOB
                  )",
        params![],
    )?;
    let me = Person {
        id: 0,
        name: "Steven".to_string(),
        time_created: time::get_time(),
        data: None,
    };
    conn.execute(
        "INSERT INTO person (name, time_created, data)
                  VALUES (?1, ?2, ?3)",
        params![me.name, me.time_created, me.data],
    )?;

    let mut stmt = conn.prepare("SELECT id, name, time_created, data FROM person")?;
    let person_iter = stmt.query_map(params![],, row, {
        Ok(Person {
            id: row.get(0)?,
            name: row.get(1)?,
            time_created: row.get(2)?,
            data: row.get(3)?,
        })
    })?;

    for person in person_iter {
        println!("Found person {:?}", person.unwrap());
    }
    Ok(())
}

Supported SQLite Versions

The base rusqlite package supports SQLite version 3.6.8 or newer. If you need
support for older versions, please file an issue. Some cargo features require a
newer SQLite version; see details below.

Optional Features

Rusqlite provides several features that are behind Cargo
features. They are:

• load_extension
  allows loading dynamic library-based SQLite extensions.
• backup
  allows use of SQLite's online backup API. Note: This feature requires SQLite 3.6.11 or later.
• functions
  allows you to load Rust closures into SQLite connections for use in queries.
  Note: This feature requires SQLite 3.7.3 or later.
• trace
  allows hooks into SQLite's tracing and profiling APIs. Note: This feature
  requires SQLite 3.6.23 or later.
• blob
  gives std::io::{Read, Write, Seek} access to SQL BLOBs. Note: This feature
  requires SQLite 3.7.4 or later.
• limits
  allows you to set and retrieve SQLite's per connection limits.
• chrono implements FromSql
  and ToSql for various
  types from the chrono crate.
• serde_json implements FromSql
  and ToSql for the
  Value type from the serde_json crate.
• url implements FromSql
  and ToSql for the
  Url type from the url crate.
• bundled uses a bundled version of sqlite3. This is a good option for cases where linking to sqlite3 is complicated, such as Windows.
• sqlcipher looks for the SQLCipher library to link against instead of SQLite. This feature is mutually exclusive with bundled.
• hooks for Commit, Rollback and Data Change notification callbacks.
• unlock_notify for Unlock notification.
• vtab for virtual table support (allows you to write virtual table implemntations in Rust). Currently, only read-only virtual tables are supported.
• csvtab, CSV virtual table written in Rust.
• array, The rarray() Table-Valued Function.
• i128_blob allows storing values of type i128 type in SQLite databases. Internally, the data is stored as a 16 byte big-endian blob, with the most significant bit flipped, which allows ordering and comparison between different blobs storing i128s to work as expected.
• uuid allows storing and retrieving Uuid values from the uuid crate using blobs.
• session, Session module extension.

Notes on building rusqlite and libsqlite3-sys

libsqlite3-sys is a separate crate from rusqlite that provides the Rust
declarations for SQLite's C API. By default, libsqlite3-sys attempts to find a SQLite library that already exists on your system using pkg-config, or a
Vcpkg installation for MSVC ABI builds.

You can adjust this behavior in a number of ways:

• If you use the bundled feature, libsqlite3-sys will use the
  cc crate to compile SQLite from source and
  link against that. This source is embedded in the libsqlite3-sys crate and
  is currently SQLite 3.30.1 (as of rusqlite 0.21.0 / libsqlite3-sys
  0.17.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in your Cargo.toml file:

  [dependencies.rusqlite]
  version = "0.21.0"
  features = ["bundled"]
  

• You can set the SQLITE3_LIB_DIR to point to directory containing the SQLite
  library.
• Installing the sqlite3 development packages will usually be all that is required, but
  the build helpers for pkg-config
  and vcpkg have some additional configuration
  options. The default when using vcpkg is to dynamically link,
  which must be enabled by setting VCPKGRS_DYNAMIC=1 environment variable before build.
  vcpkg install sqlite3:x64-windows will install the required library.

Binding generation

We use bindgen to generate the Rust
declarations from SQLite's C header file. bindgen
recommends
running this as part of the build process of libraries that used this. We tried
this briefly (rusqlite 0.10.0, specifically), but it had some annoyances:

• The build time for libsqlite3-sys (and therefore rusqlite) increased
  dramatically.
• Running bindgen requires a relatively-recent version of Clang, which many
  systems do not have installed by default.
• Running bindgen also requires the SQLite header file to be present.

As of rusqlite 0.10.1, we avoid running bindgen at build-time by shipping
pregenerated bindings for several versions of SQLite. When compiling
rusqlite, we use your selected Cargo features to pick the bindings for the
minimum SQLite version that supports your chosen features. If you are using
libsqlite3-sys directly, you can use the same features to choose which
pregenerated bindings are chosen:

• min_sqlite_version_3_6_8 - SQLite 3.6.8 bindings (this is the default)
• min_sqlite_version_3_6_23 - SQLite 3.6.23 bindings
• min_sqlite_version_3_7_7 - SQLite 3.7.7 bindings

If you use the bundled feature, you will get pregenerated bindings for the
bundled version of SQLite. If you need other specific pregenerated binding
versions, please file an issue. If you want to run bindgen at buildtime to
produce your own bindings, use the buildtime_bindgen Cargo feature.

If you enable the modern_sqlite feature, we'll use the bindings we would have
included with the bundled build. You generally should have buildtime_bindgen
enabled if you turn this on, as otherwise you'll need to keep the version of
SQLite you link with in sync with what rusqlite would have bundled, (usually the
most recent release of sqlite). Failing to do this will cause a runtime error.

Author

John Gallagher, johnkgallagher@gmail.com

License

Rusqlite is available under the MIT license. See the LICENSE file for more info.