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 params![],
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(params![], |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* [`trace`](https://docs.rs/rusqlite/~0/rusqlite/trace/index.html)
81 allows hooks into SQLite's tracing and profiling APIs. Note: This feature
82 requires SQLite 3.6.23 or later.
83* [`blob`](https://docs.rs/rusqlite/~0/rusqlite/blob/index.html)
84 gives `std::io::{Read, Write, Seek}` access to SQL BLOBs. Note: This feature
85 requires SQLite 3.7.4 or later.
86* [`limits`](https://docs.rs/rusqlite/~0/rusqlite/struct.Connection.html#method.limit)
87 allows you to set and retrieve SQLite's per connection limits.
88* `chrono` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
89 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for various
90 types from the [`chrono` crate](https://crates.io/crates/chrono).
91* `serde_json` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
92 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for the
93 `Value` type from the [`serde_json` crate](https://crates.io/crates/serde_json).
94* `time` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
95 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for the
96 `time::OffsetDateTime` type from the [`time` crate](https://crates.io/crates/time).
97* `url` implements [`FromSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.FromSql.html)
98 and [`ToSql`](https://docs.rs/rusqlite/~0/rusqlite/types/trait.ToSql.html) for the
99 `Url` type from the [`url` crate](https://crates.io/crates/url).
100* `bundled` uses a bundled version of sqlite3. This is a good option for cases where linking to sqlite3 is complicated, such as Windows.
101* `sqlcipher` looks for the SQLCipher library to link against instead of SQLite. This feature is mutually exclusive with `bundled`.
102* `hooks` for [Commit, Rollback](http://sqlite.org/c3ref/commit_hook.html) and [Data Change](http://sqlite.org/c3ref/update_hook.html) notification callbacks.
103* `unlock_notify` for [Unlock](https://sqlite.org/unlock_notify.html) notification.
104* `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.
105* [`csvtab`](https://sqlite.org/csv.html), CSV virtual table written in Rust.
106* [`array`](https://sqlite.org/carray.html), The `rarray()` Table-Valued Function.
107* `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.
108* `uuid` allows storing and retrieving `Uuid` values from the [`uuid`](https://docs.rs/uuid/) crate using blobs.
109* [`session`](https://sqlite.org/sessionintro.html), Session module extension. Requires `buildtime_bindgen` feature.
110
111## Notes on building rusqlite and libsqlite3-sys
112
113`libsqlite3-sys` is a separate crate from `rusqlite` that provides the Rust
114declarations 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
115[Vcpkg](https://github.com/Microsoft/vcpkg) installation for MSVC ABI builds.
116
117You can adjust this behavior in a number of ways:
118
119* If you use the `bundled` feature, `libsqlite3-sys` will use the
120 [cc](https://crates.io/crates/cc) crate to compile SQLite from source and
121 link against that. This source is embedded in the `libsqlite3-sys` crate and
122 is currently SQLite 3.33.0 (as of `rusqlite` 0.24.1 / `libsqlite3-sys`
123 0.20.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in your `Cargo.toml` file:
124 ```toml
125 [dependencies.rusqlite]
126 version = "0.24.2"
127 features = ["bundled"]
128 ```
129* You can set the `SQLITE3_LIB_DIR` to point to directory containing the SQLite
130 library.
131* Installing the sqlite3 development packages will usually be all that is required, but
132 the build helpers for [pkg-config](https://github.com/alexcrichton/pkg-config-rs)
133 and [vcpkg](https://github.com/mcgoo/vcpkg-rs) have some additional configuration
134 options. The default when using vcpkg is to dynamically link,
135 which must be enabled by setting `VCPKGRS_DYNAMIC=1` environment variable before build.
136 `vcpkg install sqlite3:x64-windows` will install the required library.
137
138### Binding generation
139
140We use [bindgen](https://crates.io/crates/bindgen) to generate the Rust
141declarations from SQLite's C header file. `bindgen`
142[recommends](https://github.com/servo/rust-bindgen#library-usage-with-buildrs)
143running this as part of the build process of libraries that used this. We tried
144this briefly (`rusqlite` 0.10.0, specifically), but it had some annoyances:
145
146* The build time for `libsqlite3-sys` (and therefore `rusqlite`) increased
147 dramatically.
148* Running `bindgen` requires a relatively-recent version of Clang, which many
149 systems do not have installed by default.
150* Running `bindgen` also requires the SQLite header file to be present.
151
152As of `rusqlite` 0.10.1, we avoid running `bindgen` at build-time by shipping
153pregenerated bindings for several versions of SQLite. When compiling
154`rusqlite`, we use your selected Cargo features to pick the bindings for the
155minimum SQLite version that supports your chosen features. If you are using
156`libsqlite3-sys` directly, you can use the same features to choose which
157pregenerated bindings are chosen:
158
159* `min_sqlite_version_3_6_8` - SQLite 3.6.8 bindings (this is the default)
160* `min_sqlite_version_3_6_23` - SQLite 3.6.23 bindings
161* `min_sqlite_version_3_7_7` - SQLite 3.7.7 bindings
162
163If you use the `bundled` feature, you will get pregenerated bindings for the
164bundled version of SQLite. If you need other specific pregenerated binding
165versions, please file an issue. If you want to run `bindgen` at buildtime to
166produce your own bindings, use the `buildtime_bindgen` Cargo feature.
167
168If you enable the `modern_sqlite` feature, we'll use the bindings we would have
169included with the bundled build. You generally should have `buildtime_bindgen`
170enabled if you turn this on, as otherwise you'll need to keep the version of
171SQLite you link with in sync with what rusqlite would have bundled, (usually the
172most recent release of sqlite). Failing to do this will cause a runtime error.
173
174## Contributing
175
176Rusqlite has many features, and many of them impact the build configuration in
177incompatible ways. This is unfortunate, and makes testing changes hard.
178
179To help here: you generally should ensure that you run tests/lint for
180`--features bundled`, and `--features bundled-full session buildtime_bindgen`.
181
182If running bindgen is problematic for you, `--features bundled-full` enables
183bundled and all features which don't require binding generation, and can be used
184instead.
185
186### Checklist
187
188- Run `cargo fmt` to ensure your Rust code is correctly formatted.
189- Ensure `cargo clippy --all-targets --workspace --features bundled` passes without warnings.
190- Ensure `cargo test --all-targets --workspace --features bundled-full session buildtime_bindgen` reports no failures.
191- Ensure `cargo test --all-targets --workspace --features bundled` reports no failures.
192- Ensure `cargo test --all-targets --workspace --features bundled-full session buildtime_bindgen` reports no failures.
193
194## Author
195
196Rusqlite is the product of hard work by a number of people. A list is available
197here: https://github.com/rusqlite/rusqlite/graphs/contributors
198
199## Community
200
201Currently there's a gitter channel set up for rusqlite [here](https://gitter.im/rusqlite/community).
202
203## License
204
205Rusqlite is available under the MIT license. See the LICENSE file for more info.
206
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}