README.md
1# Rusqlite
2
3[](https://travis-ci.org/rusqlite/rusqlite)
4[](https://ci.appveyor.com/project/rusqlite/rusqlite)
5[](https://github.com/rusqlite/rusqlite/actions)
6[](https://deps.rs/repo/github/rusqlite/rusqlite)
7[](https://crates.io/crates/rusqlite)
8[](https://gitter.im/rusqlite/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
9[](https://docs.rs/rusqlite)
10[](https://codecov.io/gh/rusqlite/rusqlite)
11
12Rusqlite is an ergonomic wrapper for using SQLite from Rust. It attempts to expose
13an interface similar to [rust-postgres](https://github.com/sfackler/rust-postgres).
14
15```rust
16use rusqlite::{params, Connection, Result};
17
18#[derive(Debug)]
19struct Person {
20 id: i32,
21 name: String,
22 data: Option<Vec<u8>>,
23}
24
25fn main() -> Result<()> {
26 let conn = Connection::open_in_memory()?;
27
28 conn.execute(
29 "CREATE TABLE person (
30 id INTEGER PRIMARY KEY,
31 name TEXT NOT NULL,
32 data BLOB
33 )",
34 [],
35 )?;
36 let me = Person {
37 id: 0,
38 name: "Steven".to_string(),
39 data: None,
40 };
41 conn.execute(
42 "INSERT INTO person (name, data) VALUES (?1, ?2)",
43 params![me.name, me.data],
44 )?;
45
46 let mut stmt = conn.prepare("SELECT id, name, data FROM person")?;
47 let person_iter = stmt.query_map([], |row| {
48 Ok(Person {
49 id: row.get(0)?,
50 name: row.get(1)?,
51 data: row.get(2)?,
52 })
53 })?;
54
55 for person in person_iter {
56 println!("Found person {:?}", person.unwrap());
57 }
58 Ok(())
59}
60```
61
62### Supported SQLite Versions
63
64The base `rusqlite` package supports SQLite version 3.6.8 or newer. If you need
65support for older versions, please file an issue. Some cargo features require a
66newer SQLite version; see details below.
67
68### Optional Features
69
70Rusqlite provides several features that are behind [Cargo
71features](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section). They are:
72
73* [`load_extension`](https://docs.rs/rusqlite/~0/rusqlite/struct.LoadExtensionGuard.html)
74 allows loading dynamic library-based SQLite extensions.
75* [`backup`](https://docs.rs/rusqlite/~0/rusqlite/backup/index.html)
76 allows use of SQLite's online backup API. Note: This feature requires SQLite 3.6.11 or later.
77* [`functions`](https://docs.rs/rusqlite/~0/rusqlite/functions/index.html)
78 allows you to load Rust closures into SQLite connections for use in queries.
79 Note: This feature requires SQLite 3.7.3 or later.
80* `window` for [window function](https://www.sqlite.org/windowfunctions.html) support (`fun(...) OVER ...`). (Implies `functions`.)
81* [`trace`](https://docs.rs/rusqlite/~0/rusqlite/trace/index.html)
82 allows hooks into SQLite's tracing and profiling APIs. Note: This feature
83 requires SQLite 3.6.23 or later.
84* [`blob`](https://docs.rs/rusqlite/~0/rusqlite/blob/index.html)
85 gives `std::io::{Read, Write, Seek}` access to SQL BLOBs. Note: This feature
86 requires SQLite 3.7.4 or later.
87* [`limits`](https://docs.rs/rusqlite/~0/rusqlite/struct.Connection.html#method.limit)
88 allows you to set and retrieve SQLite's per connection limits.
89* `chrono` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
90 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for various
91 types from the [`chrono` crate](https://crates.io/crates/chrono).
92* `serde_json` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
93 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for the
94 `Value` type from the [`serde_json` crate](https://crates.io/crates/serde_json).
95* `time` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
96 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for the
97 `time::OffsetDateTime` type from the [`time` crate](https://crates.io/crates/time).
98* `url` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
99 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for the
100 `Url` type from the [`url` crate](https://crates.io/crates/url).
101* `bundled` uses a bundled version of SQLite. This is a good option for cases where linking to SQLite is complicated, such as Windows.
102* `sqlcipher` looks for the SQLCipher library to link against instead of SQLite. This feature is mutually exclusive with `bundled`.
103* `hooks` for [Commit, Rollback](http://sqlite.org/c3ref/commit_hook.html) and [Data Change](http://sqlite.org/c3ref/update_hook.html) notification callbacks.
104* `unlock_notify` for [Unlock](https://sqlite.org/unlock_notify.html) notification.
105* `vtab` for [virtual table](https://sqlite.org/vtab.html) support (allows you to write virtual table implementations in Rust). Currently, only read-only virtual tables are supported.
106* `series` exposes [`generate_series(...)`](https://www.sqlite.org/series.html) Table-Valued Function. (Implies `vtab`.)
107* [`csvtab`](https://sqlite.org/csv.html), CSV virtual table written in Rust. (Implies `vtab`.)
108* [`array`](https://sqlite.org/carray.html), The `rarray()` Table-Valued Function. (Implies `vtab`.)
109* `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.
110* `uuid` allows storing and retrieving `Uuid` values from the [`uuid`](https://docs.rs/uuid/) crate using blobs.
111* [`session`](https://sqlite.org/sessionintro.html), Session module extension. Requires `buildtime_bindgen` feature. (Implies `hooks`.)
112* `extra_check` fail when a query passed to execute is readonly or has a column count > 0.
113* `column_decltype` provides `columns()` method for Statements and Rows; omit if linking to a version of SQLite/SQLCipher compiled with `-DSQLITE_OMIT_DECLTYPE`.
114* `collation` exposes [`sqlite3_create_collation_v2`](https://sqlite.org/c3ref/create_collation.html).
115
116## Notes on building rusqlite and libsqlite3-sys
117
118`libsqlite3-sys` is a separate crate from `rusqlite` that provides the Rust
119declarations 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
120[Vcpkg](https://github.com/Microsoft/vcpkg) installation for MSVC ABI builds.
121
122You can adjust this behavior in a number of ways:
123
124* If you use the `bundled` feature, `libsqlite3-sys` will use the
125 [cc](https://crates.io/crates/cc) crate to compile SQLite from source and
126 link against that. This source is embedded in the `libsqlite3-sys` crate and
127 is currently SQLite 3.35.4 (as of `rusqlite` 0.25.0 / `libsqlite3-sys`
128 0.22.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in your `Cargo.toml` file:
129 ```toml
130 [dependencies.rusqlite]
131 version = "0.25.1"
132 features = ["bundled"]
133 ```
134* When using the `bundled` feature, 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.)
135
136* When linking against a SQLite library already on the system (so *not* using the `bundled` feature), you can set the `SQLITE3_LIB_DIR` environment variable to point to a directory containing the library. You can also set the `SQLITE3_INCLUDE_DIR` variable to point to the directory containing `sqlite3.h`.
137* Installing the sqlite3 development packages will usually be all that is required, but
138 the build helpers for [pkg-config](https://github.com/alexcrichton/pkg-config-rs)
139 and [vcpkg](https://github.com/mcgoo/vcpkg-rs) have some additional configuration
140 options. The default when using vcpkg is to dynamically link,
141 which must be enabled by setting `VCPKGRS_DYNAMIC=1` environment variable before build.
142 `vcpkg install sqlite3:x64-windows` will install the required library.
143* When linking against a SQLite library already on the system, you can set the `SQLITE3_STATIC` environment variable to 1 to request that the library be statically instead of dynamically linked.
144
145
146### Binding generation
147
148We use [bindgen](https://crates.io/crates/bindgen) to generate the Rust
149declarations from SQLite's C header file. `bindgen`
150[recommends](https://github.com/servo/rust-bindgen#library-usage-with-buildrs)
151running this as part of the build process of libraries that used this. We tried
152this briefly (`rusqlite` 0.10.0, specifically), but it had some annoyances:
153
154* The build time for `libsqlite3-sys` (and therefore `rusqlite`) increased
155 dramatically.
156* Running `bindgen` requires a relatively-recent version of Clang, which many
157 systems do not have installed by default.
158* Running `bindgen` also requires the SQLite header file to be present.
159
160As of `rusqlite` 0.10.1, we avoid running `bindgen` at build-time by shipping
161pregenerated bindings for several versions of SQLite. When compiling
162`rusqlite`, we use your selected Cargo features to pick the bindings for the
163minimum SQLite version that supports your chosen features. If you are using
164`libsqlite3-sys` directly, you can use the same features to choose which
165pregenerated bindings are chosen:
166
167* `min_sqlite_version_3_6_8` - SQLite 3.6.8 bindings (this is the default)
168* `min_sqlite_version_3_6_23` - SQLite 3.6.23 bindings
169* `min_sqlite_version_3_7_7` - SQLite 3.7.7 bindings
170
171If you use the `bundled` feature, you will get pregenerated bindings for the
172bundled version of SQLite. If you need other specific pregenerated binding
173versions, please file an issue. If you want to run `bindgen` at buildtime to
174produce your own bindings, use the `buildtime_bindgen` Cargo feature.
175
176If you enable the `modern_sqlite` feature, we'll use the bindings we would have
177included with the bundled build. You generally should have `buildtime_bindgen`
178enabled if you turn this on, as otherwise you'll need to keep the version of
179SQLite you link with in sync with what rusqlite would have bundled, (usually the
180most recent release of SQLite). Failing to do this will cause a runtime error.
181
182## Contributing
183
184Rusqlite has many features, and many of them impact the build configuration in
185incompatible ways. This is unfortunate, and makes testing changes hard.
186
187To help here: you generally should ensure that you run tests/lint for
188`--features bundled`, and `--features "bundled-full session buildtime_bindgen"`.
189
190If running bindgen is problematic for you, `--features bundled-full` enables
191bundled and all features which don't require binding generation, and can be used
192instead.
193
194### Checklist
195
196- Run `cargo fmt` to ensure your Rust code is correctly formatted.
197- Ensure `cargo clippy --all-targets --workspace --features bundled` passes without warnings.
198- Ensure `cargo clippy --all-targets --workspace --features "bundled-full session buildtime_bindgen"` passes without warnings.
199- Ensure `cargo test --all-targets --workspace --features bundled` reports no failures.
200- Ensure `cargo test --all-targets --workspace --features "bundled-full session buildtime_bindgen"` reports no failures.
201
202## Author
203
204Rusqlite is the product of hard work by a number of people. A list is available
205here: https://github.com/rusqlite/rusqlite/graphs/contributors
206
207## Community
208
209Currently there's a gitter channel set up for rusqlite [here](https://gitter.im/rusqlite/community).
210
211## License
212
213Rusqlite is available under the MIT license. See the LICENSE file for more info.
214
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}