rusqlite/README.md

148 lines
6.6 KiB
Markdown
Raw Normal View History

2014-11-05 00:32:06 +08:00
# Rusqlite
2016-02-02 03:19:51 +08:00
[![Travis Build Status](https://api.travis-ci.org/jgallagher/rusqlite.svg?branch=master)](https://travis-ci.org/jgallagher/rusqlite)
2016-10-08 02:14:09 +08:00
[![AppVeyor Build Status](https://ci.appveyor.com/api/projects/status/github/jgallagher/rusqlite?branch=master&svg=true)](https://ci.appveyor.com/project/jgallagher/rusqlite) [![Latest Version](https://img.shields.io/crates/v/rusqlite.svg)](https://crates.io/crates/rusqlite)
2014-11-05 01:48:33 +08:00
Rusqlite is an ergonomic wrapper for using SQLite from Rust. It attempts to expose
2014-11-05 04:36:04 +08:00
an interface similar to [rust-postgres](https://github.com/sfackler/rust-postgres). View the full
[API documentation](http://jgallagher.github.io/rusqlite/rusqlite/index.html).
2014-11-05 00:32:06 +08:00
```rust
extern crate rusqlite;
extern crate time;
use time::Timespec;
use rusqlite::Connection;
2014-11-05 00:32:06 +08:00
#[derive(Debug)]
2014-11-05 00:32:06 +08:00
struct Person {
id: i32,
name: String,
time_created: Timespec,
data: Option<Vec<u8>>
}
fn main() {
let conn = Connection::open_in_memory().unwrap();
2014-11-05 00:32:06 +08:00
conn.execute("CREATE TABLE person (
id INTEGER PRIMARY KEY,
name TEXT NOT NULL,
time_created TEXT NOT NULL,
data BLOB
)", &[]).unwrap();
2014-11-05 00:32:06 +08:00
let me = Person {
id: 0,
name: "Steven".to_string(),
time_created: time::get_time(),
data: None
};
conn.execute("INSERT INTO person (name, time_created, data)
2016-07-02 16:22:47 +08:00
VALUES (?1, ?2, ?3)",
2014-11-05 00:32:06 +08:00
&[&me.name, &me.time_created, &me.data]).unwrap();
let mut stmt = conn.prepare("SELECT id, name, time_created, data FROM person").unwrap();
2016-08-15 18:41:15 +08:00
let person_iter = stmt.query_map(&[], |row| {
Person {
2014-11-05 00:32:06 +08:00
id: row.get(0),
name: row.get(1),
time_created: row.get(2),
data: row.get(3)
}
}).unwrap();
for person in person_iter {
println!("Found person {:?}", person.unwrap());
2014-11-05 00:32:06 +08:00
}
}
```
### Supported SQLite Versions
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.
2015-12-13 05:04:11 +08:00
### Optional Features
Rusqlite provides several features that are behind [Cargo
features](http://doc.crates.io/manifest.html#the-features-section). They are:
* [`load_extension`](http://jgallagher.github.io/rusqlite/rusqlite/struct.LoadExtensionGuard.html)
allows loading dynamic library-based SQLite extensions.
* [`backup`](http://jgallagher.github.io/rusqlite/rusqlite/backup/index.html)
allows use of SQLite's online backup API. Note: This feature requires SQLite 3.6.11 or later.
2015-12-13 05:04:11 +08:00
* [`functions`](http://jgallagher.github.io/rusqlite/rusqlite/functions/index.html)
allows you to load Rust closures into SQLite connections for use in queries.
Note: This feature requires SQLite 3.7.3 or later.
2015-12-13 05:04:11 +08:00
* [`trace`](http://jgallagher.github.io/rusqlite/rusqlite/trace/index.html)
allows hooks into SQLite's tracing and profiling APIs. Note: This feature
requires SQLite 3.6.23 or later.
* [`blob`](http://jgallagher.github.io/rusqlite/rusqlite/blob/index.html)
gives `std::io::{Read, Write, Seek}` access to SQL BLOBs. Note: This feature
requires SQLite 3.7.4 or later.
2017-02-08 08:47:59 +08:00
* [`limits`](http://jgallagher.github.io/rusqlite/rusqlite/struct.Connection.html#method.limit)
allows you to set and retrieve SQLite's per connection limits.
2016-05-20 09:20:58 +08:00
* `chrono` implements [`FromSql`](http://jgallagher.github.io/rusqlite/rusqlite/types/trait.FromSql.html)
and [`ToSql`](http://jgallagher.github.io/rusqlite/rusqlite/types/trait.ToSql.html) for various
types from the [`chrono` crate](https://crates.io/crates/chrono).
* `serde_json` implements [`FromSql`](http://jgallagher.github.io/rusqlite/rusqlite/types/trait.FromSql.html)
and [`ToSql`](http://jgallagher.github.io/rusqlite/rusqlite/types/trait.ToSql.html) for the
`Value` type from the [`serde_json` crate](https://crates.io/crates/serde_json).
* `bundled` uses a bundled version of sqlite3. This is a good option for cases where linking to sqlite3 is complicated, such as Windows.
2015-12-13 05:04:11 +08:00
2017-03-04 04:37:15 +08:00
## Notes on building rusqlite and libsqlite3-sys
`libsqlite3-sys` is a separate crate from `rusqlite` that provides the Rust
declarations for SQLite's C API. By default, `libsqlite3-sys` attempts to use
pkg-config to find a SQLite library that already exists on your system. You can
adjust this behavior in a couple of ways:
* If you use the `bundled` feature, `libsqlite3-sys` will use the
[gcc](https://crates.io/crates/gcc) crate to compile SQLite from source and
link against that. This source is embedded in the `libsqlite3-sys` crate and
is currently SQLite 3.17.0 (as of `rusqlite` 0.10.1 / `libsqlite3-sys`
0.7.1). This is probably the simplest solution to any build problems.
* You can set the `SQLITE3_LIB_DIR` to point to directory containing the SQLite
library.
### Binding generation
We use [bindgen](https://crates.io/crates/bindgen) to generate the Rust
declarations from SQLite's C header file. `bindgen`
[recommends](https://github.com/servo/rust-bindgen#library-usage-with-buildrs)
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:
* The build time for `libsqlite3-sys` (and therefore `rusqlite`) increased
dramatically.
* Running `bindgen` requires a relatively-recent version of Clang, which many
systems do not have installed by default.
* Running `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_11` - SQLite 3.6.11 bindings
* `min_sqlite_version_3_6_23` - SQLite 3.6.23 bindings
* `min_sqlite_version_3_7_3` - SQLite 3.7.3 bindings
* `min_sqlite_version_3_7_4` - SQLite 3.7.4 bindings
If 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.
2014-11-05 00:32:06 +08:00
## Author
John Gallagher, johnkgallagher@gmail.com
## License
Rusqlite is available under the MIT license. See the LICENSE file for more info.