rusqlite

Rusqlite

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:

…

Simple example usage:

…

Supported SQLite Versions

The base rusqlite package supports SQLite version 3.45.3 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.
• loadable_extension to program loadable extension in Rust.
• backup allows use of SQLite's online backup API.
• functions allows you to load Rust closures into SQLite connections for use in queries.
• window for window function support (fun(...) OVER ...). (Implies functions.)
• trace allows hooks into SQLite's tracing and profiling APIs.
• blob gives std::io::{Read, Write, Seek} access to SQL BLOBs.
• limits allows you to set and retrieve SQLite's per connection limits.
• serde_json implements FromSql and ToSql for the Value type from the serde_json crate.
• chrono implements FromSql and ToSql for various types from the chrono crate.
• time implements FromSql and ToSql for various types from the time crate.
• jiff implements FromSql and ToSql for the Value type from the jiff crate.
• url implements FromSql and ToSql for the Url type from the url crate.
• bundled uses a bundled version of SQLite. This is a good option for cases where linking to SQLite is complicated, such as Windows.
• sqlcipher looks for the SQLCipher library to link against instead of SQLite. This feature overrides bundled.
• bundled-sqlcipher uses a bundled version of SQLCipher. This searches for and links against a system-installed crypto library to provide the crypto implementation.
• bundled-sqlcipher-vendored-openssl allows using bundled-sqlcipher with a vendored version of OpenSSL (via the openssl-sys crate) as the crypto provider.
  • As the name implies this depends on the bundled-sqlcipher feature, and automatically turns it on.
  • If turned on, this uses the openssl-sys crate, with the vendored feature enabled in order to build and bundle the OpenSSL crypto library.
• hooks for Commit, Rollback and Data Change notification callbacks.
• preupdate_hook for preupdate notification callbacks. (Implies hooks.)
• unlock_notify for Unlock notification.
• vtab for virtual table support (allows you to write virtual table implementations in Rust). Currently, only read-only virtual tables are supported.
• series exposes generate_series(...) Table-Valued Function. (Implies vtab.)
• csvtab, CSV virtual table written in Rust. (Implies vtab.)
• array, The rarray() Table-Valued Function. (Implies vtab.)
• fallible_uint allows storing values of type u64, usize, NonZeroU64, NonZeroUsize but only if <= i64::MAX.
• 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. Requires buildtime_bindgen feature. (Implies hooks.)
• extra_check fails when a query passed to execute is readonly and has a column count > 0.
• column_decltype provides columns() method for Statements and Rows; omit if linking to a version of SQLite/SQLCipher compiled with -DSQLITE_OMIT_DECLTYPE.
• collation exposes sqlite3_create_collation_v2.
• serialize exposes sqlite3_serialize (3.23.0).
• rusqlite-macros enables the use of the prepare_and_bind and prepare_cached_and_bind procedural macros, which allow capturing identifiers in SQL statements.
• ffi-sqlite-wasm-rs switches to using the sqlite-wasm-rs crate (instead of libsqlite3-sys) on wasm32-unknown-unknown builds. This is enabled by default and can be opted out by setting default-features = false.

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, bundled-sqlcipher, or bundled-sqlcipher-vendored-openssl features, libsqlite3-sys will use the cc crate to compile SQLite or SQLCipher from source and link against that. This source is embedded in the libsqlite3-sys crate and is currently SQLite 3.53.2 (as of rusqlite 0.40.1 / libsqlite3-sys 0.38.1). 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.40.1"
  features = ["bundled"]
  

• When using any of the bundled features, the build script will honor SQLITE_MAX_VARIABLE_NUMBER and SQLITE_MAX_EXPR_DEPTH variables. It will also honor a LIBSQLITE3_FLAGS variable, which can have a format like "-USQLITE_ALPHA -DSQLITE_BETA SQLITE_GAMMA ...". That would disable the SQLITE_ALPHA flag, and set the SQLITE_BETA and SQLITE_GAMMA flags. (The initial -D can be omitted, as on the last one.)

• When using bundled-sqlcipher (and not also using bundled-sqlcipher-vendored-openssl), libsqlite3-sys will need to link against crypto libraries on the system. If the build script can find a libcrypto from OpenSSL or LibreSSL (it will consult OPENSSL_LIB_DIR/OPENSSL_INCLUDE_DIR and OPENSSL_DIR environment variables), it will use that. If building on and for Macs, and none of those variables are set, it will use the system's SecurityFramework instead.

• When linking against a SQLite (or SQLCipher) library already on the system (so not using any of the bundled features), you can set the SQLITE3_LIB_DIR (or SQLCIPHER_LIB_DIR) environment variable to point to a directory containing the library. You can also set the SQLITE3_INCLUDE_DIR (or SQLCIPHER_INCLUDE_DIR) variable to point to the directory containing sqlite3.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=1 environment variable before build. vcpkg install sqlite3:x64-windows will install the required library.

• When linking against a SQLite (or SQLCipher) library already on the system, you can set the SQLITE3_STATIC (or SQLCIPHER_STATIC) environment 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 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_45_3 - SQLite 3.45.3 bindings (this is the default)

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

• Run cargo fmt to ensure your Rust code is correctly formatted.
• Ensure cargo clippy --workspace --features bundled passes without warnings.
• Ensure `ca