Home

Awesome

Rusqlite

Latest Version Documentation Build Status (GitHub) Build Status (AppVeyor) Code Coverage Dependency Status Discord Chat

Rusqlite is an ergonomic wrapper for using SQLite from Rust.

Historically, the API was based on the one from rust-postgres. However, the two have diverged in many ways, and no compatibility between the two is intended.

Usage

In your Cargo.toml:

[dependencies]
# `bundled` causes us to automatically compile and link in an up to date
# version of SQLite for you. This avoids many common build issues, and
# avoids depending on the version of SQLite on the users system (or your
# system), which may be old or missing. It's the right choice for most
# programs that control their own SQLite databases.
#
# That said, it's not ideal for all scenarios and in particular, generic
# libraries built around `rusqlite` should probably not enable it, which
# is why it is not a default feature -- it could become hard to disable.
rusqlite = { version = "0.29.0", features = ["bundled"] }

Simple example usage:

use rusqlite::{Connection, Result};

#[derive(Debug)]
struct Person {
    id: i32,
    name: String,
    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,
            data  BLOB
        )",
        (), // empty list of parameters.
    )?;
    let me = Person {
        id: 0,
        name: "Steven".to_string(),
        data: None,
    };
    conn.execute(
        "INSERT INTO person (name, data) VALUES (?1, ?2)",
        (&me.name, &me.data),
    )?;

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

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

Supported SQLite Versions

The base rusqlite package supports SQLite version 3.14.0 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:

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:

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:

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:

If you use any of the bundled features, you will get pregenerated bindings for the bundled version of SQLite/SQLCipher. 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.

Contributing

Rusqlite has many features, and many of them impact the build configuration in incompatible ways. This is unfortunate, and makes testing changes hard.

To help here: you generally should ensure that you run tests/lint for --features bundled, and --features "bundled-full session buildtime_bindgen".

If running bindgen is problematic for you, --features bundled-full enables bundled and all features which don't require binding generation, and can be used instead.

Checklist

Author

Rusqlite is the product of hard work by a number of people. A list is available here: https://github.com/rusqlite/rusqlite/graphs/contributors

Community

Feel free to join the Rusqlite Discord Server to discuss or get help with rusqlite or libsqlite3-sys.

License

Rusqlite and libsqlite3-sys are available under the MIT license. See the LICENSE file for more info.

Licenses of Bundled Software

Depending on the set of enabled cargo features, rusqlite and libsqlite3-sys will also bundle other libraries, which have their own licensing terms:

Both of these are quite permissive, have no bearing on the license of the code in rusqlite or libsqlite3-sys themselves, and can be entirely ignored if you do not use the feature in question.