commit | e9b4c66b2f2a537621227ada98e661d6f955cde3 | [log] [tgz] |
---|---|---|
author | Joel Galenson <jgalenson@google.com> | Fri Jul 31 18:03:04 2020 +0000 |
committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | Fri Jul 31 18:03:04 2020 +0000 |
tree | 442521f3ec96571e4c32a7d0894e75e82e64c2dc | |
parent | 57ac10906603c63e0511b65fe755e8102df24e1f [diff] | |
parent | 9c18ebc6e1273171bf982328335d5744b42fe4c0 [diff] |
Add metadata files am: b77ca45fd7 am: 9c18ebc6e1 Original change: https://android-review.googlesource.com/c/platform/external/rust/crates/rusqlite/+/1375105 Change-Id: Ib49d21b501a68ba931723fa84275cbbf6e2a6ee7
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 )", params![], )?; 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(params![], |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(()) }
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.
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. Requires buildtime_bindgen
feature.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:
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"]
SQLITE3_LIB_DIR
to point to directory containing the SQLite library.VCPKGRS_DYNAMIC=1
environment variable before build. vcpkg install sqlite3:x64-windows
will install the required library.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:
libsqlite3-sys
(and therefore rusqlite
) increased dramatically.bindgen
requires a relatively-recent version of Clang, which many systems do not have installed by default.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 bindingsmin_sqlite_version_3_7_7
- SQLite 3.7.7 bindingsIf 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.
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.
cargo fmt
to ensure your Rust code is correctly formatted.cargo clippy --all-targets --workspace --features bundled
passes without warnings.cargo test --all-targets --workspace --features bundled-full session buildtime_bindgen
reports no failures.cargo test --all-targets --workspace --features bundled
reports no failures.cargo test --all-targets --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 available here: https://github.com/rusqlite/rusqlite/graphs/contributors
Rusqlite is available under the MIT license. See the LICENSE file for more info.