Name |
Date |
Size |
#Lines |
LOC |
||
---|---|---|---|---|---|---|
.. | - | - | ||||
.github/workflows/ | 03-May-2024 | - | 154 | 117 | ||
benches/ | 03-May-2024 | - | 37 | 29 | ||
src/ | 03-May-2024 | - | 15,213 | 10,685 | ||
tests/ | 03-May-2024 | - | 161 | 120 | ||
.cargo_vcs_info.json | D | 03-May-2024 | 74 | 6 | 5 | |
.gitattributes | D | 03-May-2024 | 43 | 2 | 1 | |
.gitignore | D | 03-May-2024 | 26 | 4 | 3 | |
.travis.yml | D | 03-May-2024 | 1.6 KiB | 49 | 42 | |
Android.bp | D | 03-May-2024 | 1.3 KiB | 49 | 44 | |
Cargo.toml | D | 03-May-2024 | 4 KiB | 170 | 137 | |
Cargo.toml.orig | D | 03-May-2024 | 4.2 KiB | 156 | 140 | |
Changelog.md | D | 03-May-2024 | 15.7 KiB | 333 | 256 | |
LICENSE | D | 03-May-2024 | 1 KiB | 20 | 16 | |
METADATA | D | 03-May-2024 | 370 | 20 | 19 | |
MODULE_LICENSE_MIT | D | 03-May-2024 | 0 | |||
OWNERS | D | 03-May-2024 | 40 | 2 | 1 | |
README.md | D | 03-May-2024 | 10.6 KiB | 206 | 169 | |
appveyor.yml | D | 03-May-2024 | 2.3 KiB | 43 | 28 | |
clippy.toml | D | 03-May-2024 | 50 | 2 | 1 | |
codecov.yml | D | 03-May-2024 | 205 | 12 | 11 | |
publish-ghp-docs.sh | D | 03-May-2024 | 512 | 15 | 11 | |
test.csv | D | 03-May-2024 | 72 | 7 | 6 |
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