diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 48 |
1 files changed, 35 insertions, 13 deletions
@@ -8,11 +8,32 @@ [](https://deps.rs/repo/github/rusqlite/rusqlite) [](https://discord.gg/nFYfGPB8g4) -Rusqlite is an ergonomic wrapper for using SQLite from Rust. It attempts to expose -an interface similar to [rust-postgres](https://github.com/sfackler/rust-postgres). +Rusqlite is an ergonomic wrapper for using SQLite from Rust. + +Historically, the API was based on the one from [`rust-postgres`](https://github.com/sfackler/rust-postgres). However, the two have diverged in many ways, and no compatibility between the two is intended. + +## Usage + +In your Cargo.toml: + +```toml +[dependencies] +# `bundled` causes us to automatically compile and link in an up to date +# version of SQLite for you. This avoids many common build issues, and +# avoids depending on the version of SQLite on the users system (or your +# system), which may be old or missing. It's the right choice for most +# programs that control their own SQLite databases. +# +# That said, it's not ideal for all scenarios and in particular, generic +# libraries built around `rusqlite` should probably not enable it, which +# is why it is not a default feature -- it could become hard to disable. +rusqlite = { version = "0.28.0", features = ["bundled"] } +``` + +Simple example usage: ```rust -use rusqlite::{params, Connection, Result}; +use rusqlite::{Connection, Result}; #[derive(Debug)] struct Person { @@ -26,11 +47,11 @@ fn main() -> Result<()> { conn.execute( "CREATE TABLE person ( - id INTEGER PRIMARY KEY, - name TEXT NOT NULL, - data BLOB - )", - [], + id INTEGER PRIMARY KEY, + name TEXT NOT NULL, + data BLOB + )", + (), // empty list of parameters. )?; let me = Person { id: 0, @@ -39,7 +60,7 @@ fn main() -> Result<()> { }; conn.execute( "INSERT INTO person (name, data) VALUES (?1, ?2)", - params![me.name, me.data], + (&me.name, &me.data), )?; let mut stmt = conn.prepare("SELECT id, name, data FROM person")?; @@ -115,6 +136,7 @@ features](https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-s * `extra_check` fail when a query passed to execute is readonly or has a column count > 0. * `column_decltype` provides `columns()` method for Statements and Rows; omit if linking to a version of SQLite/SQLCipher compiled with `-DSQLITE_OMIT_DECLTYPE`. * `collation` exposes [`sqlite3_create_collation_v2`](https://sqlite.org/c3ref/create_collation.html). +* `winsqlite3` allows linking against the SQLite present in newer versions of Windows ## Notes on building rusqlite and libsqlite3-sys @@ -127,14 +149,14 @@ You can adjust this behavior in a number of ways: * If you use the `bundled`, `bundled-sqlcipher`, or `bundled-sqlcipher-vendored-openssl` features, `libsqlite3-sys` will use the [cc](https://crates.io/crates/cc) crate to compile SQLite or SQLCipher from source and link against that. This source is embedded in the `libsqlite3-sys` crate and - is currently SQLite 3.38.0 (as of `rusqlite` 0.27.0 / `libsqlite3-sys` - 0.24.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in your `Cargo.toml` file: + is currently SQLite 3.39.0 (as of `rusqlite` 0.28.0 / `libsqlite3-sys` + 0.25.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in your `Cargo.toml` file: ```toml [dependencies.rusqlite] - version = "0.27.0" + version = "0.28.0" features = ["bundled"] ``` -* When using any of the `bundled` features, the build script will honor `SQLITE_MAX_VARIABLE_NUMBER` and `SQLITE_MAX_EXPR_DEPTH` variables. It will also honor a `LIBSQLITE_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.) +* When using any of the `bundled` features, 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.) * When using `bundled-sqlcipher` (and not also using `bundled-sqlcipher-vendored-openssl`), `libsqlite3-sys` will need to link against crypto libraries on the system. If the build script can find a `libcrypto` from OpenSSL or LibreSSL (it will consult `OPENSSL_LIB_DIR`/`OPENSSL_INCLUDE_DIR` and `OPENSSL_DIR` environment variables), it will use that. If building on and for Macs, and none of those variables are set, it will use the system's SecurityFramework instead. |