Repository files navigation

Rusqlite is an ergonomic wrapper for using SQLite from Rust.

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

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.37.0",features = ["bundled"] }

Simple example usage:

use rusqlite::{Connection,Result};#[derive(Debug)]structPerson{id:i32,name:String,data:Option<Vec<u8>>,}fnmain() ->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),)?;letmut 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 personin person_iter{println!("Found person {:?}", person.unwrap());}Ok(())}

The baserusqlite package supports SQLite version 3.14.0 or newer. If you needsupport for older versions, please file an issue. Some cargo features require anewer SQLite version; see details below.

Rusqlite provides several features that are behindCargofeatures. They are:

• load_extensionallows loading dynamic library-based SQLite extensions.
• loadable_extension to programloadable extension in Rust.
• backupallows use of SQLite's online backup API.
• functionsallows you to load Rust closures into SQLite connections for use in queries.
• window forwindow function support (fun(...) OVER ...). (Impliesfunctions.)
• traceallows hooks into SQLite's tracing and profiling APIs.
• blobgivesstd::io::{Read, Write, Seek} access to SQL BLOBs.
• limitsallows you to set and retrieve SQLite's per connection limits.
• serde_json implementsFromSqlandToSql for theValue type from theserde_json crate.
• chrono implementsFromSqlandToSql for varioustypes from thechrono crate.
• time implementsFromSqlandToSql for varioustypes from thetime crate.
• jiff implementsFromSqlandToSql for theValue type from thejiff crate.
• url implementsFromSqlandToSql for theUrl type from theurl 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 overridesbundled.
• 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 theopenssl-sys crate) as the crypto provider.
  • As the name implies this depends on thebundled-sqlcipher feature, and automatically turns it on.
  • If turned on, this uses theopenssl-sys crate, with thevendored feature enabled in order to build and bundle the OpenSSL crypto library.
• hooks forCommit, Rollback andData Change notification callbacks.
• preupdate_hook forpreupdate notification callbacks. (Implieshooks.)
• unlock_notify forUnlock notification.
• vtab forvirtual table support (allows you to write virtual table implementations in Rust). Currently, only read-only virtual tables are supported.
• series exposesgenerate_series(...) Table-Valued Function. (Impliesvtab.)
• csvtab, CSV virtual table written in Rust. (Impliesvtab.)
• array, Therarray() Table-Valued Function. (Impliesvtab.)
• i128_blob allows storing values of typei128 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 retrievingUuid values from theuuid crate using blobs.
• session, Session module extension. Requiresbuildtime_bindgen feature. (Implieshooks.)
• extra_check fails when a query passed toexecute is readonly and has a column count > 0.
• column_decltype providescolumns() method for Statements and Rows; omit if linking to a version of SQLite/SQLCipher compiled with-DSQLITE_OMIT_DECLTYPE.
• collation exposessqlite3_create_collation_v2.
• serialize exposessqlite3_serialize (3.23.0).
• rusqlite-macros enables the use of theprepare_and_bindandprepare_cached_and_bindprocedural macros, which allow capturing identifiers in SQL statements.

libsqlite3-sys is a separate crate fromrusqlite that provides the Rustdeclarations 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 aVcpkg installation for MSVC ABI builds.

You can adjust this behavior in a number of ways:

• If you use thebundled,bundled-sqlcipher, orbundled-sqlcipher-vendored-openssl features,libsqlite3-sys will use thecc crate to compile SQLite or SQLCipher from source andlink against that. This source is embedded in thelibsqlite3-sys crate andis currently SQLite 3.50.2 (as ofrusqlite 0.37.0 /libsqlite3-sys0.35.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in yourCargo.toml file:

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

• When using any of thebundled features, the build script will honorSQLITE_MAX_VARIABLE_NUMBER andSQLITE_MAX_EXPR_DEPTH variables. It will also honor aLIBSQLITE3_FLAGS variable, which can have a format like"-USQLITE_ALPHA -DSQLITE_BETA SQLITE_GAMMA ...". That would disable theSQLITE_ALPHA flag, and set theSQLITE_BETA andSQLITE_GAMMA flags. (The initial-D can be omitted, as on the last one.)

• When usingbundled-sqlcipher (and not also usingbundled-sqlcipher-vendored-openssl),libsqlite3-sys will need tolink against crypto libraries on the system. If the build script can find alibcrypto from OpenSSL or LibreSSL (it will consultOPENSSL_LIB_DIR/OPENSSL_INCLUDE_DIR andOPENSSL_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 (sonot using any of thebundled features), you can set theSQLITE3_LIB_DIR (orSQLCIPHER_LIB_DIR) environment variable to point to a directory containing the library. You can also set theSQLITE3_INCLUDE_DIR (orSQLCIPHER_INCLUDE_DIR) variable to point to the directory containingsqlite3.h.

• Installing the sqlite3 development packages will usually be all that is required, butthe build helpers forpkg-configandvcpkg have some additional configurationoptions. The default when using vcpkg is to dynamically link,which must be enabled by settingVCPKGRS_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 theSQLITE3_STATIC (orSQLCIPHER_STATIC) environment variable to 1 to request that the library be statically instead of dynamically linked.

We usebindgen to generate the Rustdeclarations from SQLite's C header file.bindgenrecommendsrunning this as part of the build process of libraries that used this. We triedthis briefly (rusqlite 0.10.0, specifically), but it had some annoyances:

• The build time forlibsqlite3-sys (and thereforerusqlite) increaseddramatically.
• Runningbindgen requires a relatively-recent version of Clang, which manysystems do not have installed by default.
• Runningbindgen also requires the SQLite header file to be present.

As ofrusqlite 0.10.1, we avoid runningbindgen at build-time by shippingpregenerated bindings for several versions of SQLite. When compilingrusqlite, we use your selected Cargo features to pick the bindings for theminimum SQLite version that supports your chosen features. If you are usinglibsqlite3-sys directly, you can use the same features to choose whichpregenerated bindings are chosen:

• min_sqlite_version_3_14_0 - SQLite 3.14.0 bindings (this is the default)

If you use any of thebundled features, you will get pregenerated bindings for thebundled version of SQLite/SQLCipher. If you need other specific pregenerated bindingversions, please file an issue. If you want to runbindgen at buildtime toproduce your own bindings, use thebuildtime_bindgen Cargo feature.

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

Rusqlite has many features, and many of them impact the build configuration inincompatible 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 enablesbundled and all features which don't require binding generation, and can be usedinstead.

• Runcargo fmt to ensure your Rust code is correctly formatted.
• Ensurecargo clippy --workspace --features bundled passes without warnings.
• Ensurecargo clippy --workspace --features "bundled-full session buildtime_bindgen" passes without warnings.
• Ensurecargo test --workspace --features bundled reports no failures.
• Ensurecargo test --workspace --features "bundled-full session buildtime_bindgen" reports no failures.

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

Feel free to join theRusqlite Discord Server to discuss or get help withrusqlite orlibsqlite3-sys.

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

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

• If--features=bundled-sqlcipher is enabled, the vendored source ofSQLcipher will be compiled and statically linked in. SQLcipher is distributed under a BSD-style license, as describedhere.

• If--features=bundled is enabled, the vendored source of SQLite will be compiled and linked in. SQLite is in the public domain, as describedhere.

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

Latest stable Rust version at the time of release. It might compile with older versions.