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};
#[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
)",
[],
)?;
let me = Person {
id: 0,
name: "Steven".to_string(),
data: None,
};
conn.execute(
"INSERT INTO person (name, data) VALUES (?1, ?2)",
params![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.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_extensionallows loading dynamic library-based SQLite extensions.backupallows use of SQLite's online backup API. Note: This feature requires SQLite 3.6.11 or later.functionsallows you to load Rust closures into SQLite connections for use in queries. Note: This feature requires SQLite 3.7.3 or later.windowfor window function support (fun(...) OVER ...). (Impliesfunctions.)traceallows hooks into SQLite's tracing and profiling APIs. Note: This feature requires SQLite 3.6.23 or later.blobgivesstd::io::{Read, Write, Seek}access to SQL BLOBs. Note: This feature requires SQLite 3.7.4 or later.limitsallows you to set and retrieve SQLite's per connection limits.chronoimplementsFromSqlandToSqlfor various types from thechronocrate.serde_jsonimplementsFromSqlandToSqlfor theValuetype from theserde_jsoncrate.timeimplementsFromSqlandToSqlfor thetime::OffsetDateTimetype from thetimecrate.urlimplementsFromSqlandToSqlfor theUrltype from theurlcrate.bundleduses a bundled version of SQLite. This is a good option for cases where linking to SQLite is complicated, such as Windows.sqlcipherlooks for the SQLCipher library to link against instead of SQLite. This feature is mutually exclusive withbundled.hooksfor Commit, Rollback and Data Change notification callbacks.unlock_notifyfor Unlock notification.vtabfor virtual table support (allows you to write virtual table implementations in Rust). Currently, only read-only virtual tables are supported.seriesexposesgenerate_series(...)Table-Valued Function. (Impliesvtab.)csvtab, CSV virtual table written in Rust. (Impliesvtab.)array, Therarray()Table-Valued Function. (Impliesvtab.)i128_bloballows storing values of typei128type 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.uuidallows storing and retrievingUuidvalues from theuuidcrate using blobs.session, Session module extension. Requiresbuildtime_bindgenfeature. (Implieshooks.)extra_checkfail when a query passed to execute is readonly or has a column count > 0.column_decltypeprovidescolumns()method for Statements and Rows; omit if linking to a version of SQLite/SQLCipher compiled with-DSQLITE_OMIT_DECLTYPE.collationexposessqlite3_create_collation_v2.
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
bundledfeature,libsqlite3-syswill use the cc crate to compile SQLite from source and link against that. This source is embedded in thelibsqlite3-syscrate and is currently SQLite 3.34.0 (as ofrusqlite0.24.1 /libsqlite3-sys0.21.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in yourCargo.tomlfile:[dependencies.rusqlite] version = "0.24.2" features = ["bundled"]
-
When using the
bundledfeature, the build script will honorSQLITE_MAX_VARIABLE_NUMBERandSQLITE_MAX_EXPR_DEPTHvariables. It will also honor aLIBSQLITE3_FLAGSvariable, which can have a format like"-USQLITE_ALPHA -DSQLITE_BETA SQLITE_GAMMA ...". That would disable theSQLITE_ALPHAflag, and set theSQLITE_BETAandSQLITE_GAMMAflags. (The initial-Dcan be omitted, as on the last one.) -
When linking against a SQLite library already on the system (so not using the
bundledfeature), you can set theSQLITE3_LIB_DIRenvironment variable to point to a directory containing the library. You can also set theSQLITE3_INCLUDE_DIRvariable to point to the directory containingsqlite3.h. -
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=1environment variable before build.vcpkg install sqlite3:x64-windowswill install the required library. -
When linking against a SQLite library already on the system, you can set the
SQLITE3_STATICenvironment variable to 1 to request that the library be statically instead of dynamically linked.
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 thereforerusqlite) increased dramatically. - Running
bindgenrequires a relatively-recent version of Clang, which many systems do not have installed by default. - Running
bindgenalso 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 bindingsmin_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.
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
- Run
cargo fmtto ensure your Rust code is correctly formatted. - Ensure
cargo clippy --all-targets --workspace --features bundledpasses without warnings. - Ensure
cargo clippy --all-targets --workspace --features "bundled-full session buildtime_bindgen"passes without warnings. - Ensure
cargo test --all-targets --workspace --features bundledreports no failures. - Ensure
cargo test --all-targets --workspace --features "bundled-full session buildtime_bindgen"reports no failures.
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
Currently there's a gitter channel set up for rusqlite here.
License
Rusqlite is available under the MIT license. See the LICENSE file for more info.
16 Jan 2, 2023
126 Dec 30, 2022
7.6k Dec 31, 2022
952 Jan 5, 2023
14 Dec 5, 2022
516 Jan 2, 2023
10 Nov 13, 2022
56 Dec 19, 2022
0 Dec 19, 2022
3 May 19, 2023
21 Jun 1, 2023
6 Oct 6, 2023
27 Nov 22, 2022
309 Dec 20, 2022
20 Jan 2, 2023
45 Nov 16, 2022
139 Dec 28, 2022
5 Sep 23, 2022