Giter VIP home page Giter VIP logo

rusqlite's Introduction

Rusqlite

Travis Build Status AppVeyor Build Status Build Status dependency status Latest Version Gitter Docs codecov

Rusqlite is an ergonomic wrapper for using SQLite from Rust. It attempts to expose an interface similar to rust-postgres.

use rusqlite::{params, Connection, Result};

#[derive(Debug)]
struct Person {
    id: i32,
    name: String,
    data: Option<Vec<u8>>,
}

fn main() -> Result<()> {
    let conn = Connection::open_in_memory()?;

    conn.execute(
        "CREATE TABLE person (
                  id              INTEGER PRIMARY KEY,
                  name            TEXT NOT NULL,
                  data            BLOB
                  )",
        [],
    )?;
    let me = Person {
        id: 0,
        name: "Steven".to_string(),
        data: None,
    };
    conn.execute(
        "INSERT INTO person (name, data) VALUES (?1, ?2)",
        params![me.name, me.data],
    )?;

    let mut stmt = conn.prepare("SELECT id, name, data FROM person")?;
    let person_iter = stmt.query_map([], |row| {
        Ok(Person {
            id: row.get(0)?,
            name: row.get(1)?,
            data: row.get(2)?,
        })
    })?;

    for person in person_iter {
        println!("Found person {:?}", person.unwrap());
    }
    Ok(())
}

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.

Optional Features

Rusqlite provides several features that are behind Cargo features. They are:

  • load_extension allows loading dynamic library-based SQLite extensions.
  • backup allows use of SQLite's online backup API. Note: This feature requires SQLite 3.6.11 or later.
  • functions allows you to load Rust closures into SQLite connections for use in queries. Note: This feature requires SQLite 3.7.3 or later.
  • trace allows hooks into SQLite's tracing and profiling APIs. Note: This feature requires SQLite 3.6.23 or later.
  • blob gives std::io::{Read, Write, Seek} access to SQL BLOBs. Note: This feature requires SQLite 3.7.4 or later.
  • limits allows you to set and retrieve SQLite's per connection limits.
  • chrono implements FromSql and ToSql for various types from the chrono crate.
  • serde_json implements FromSql and ToSql for the Value type from the serde_json crate.
  • time implements FromSql and ToSql for the time::OffsetDateTime type from the time crate.
  • url implements FromSql and ToSql for the Url type from the url crate.
  • bundled uses a bundled version of sqlite3. This is a good option for cases where linking to sqlite3 is complicated, such as Windows.
  • sqlcipher looks for the SQLCipher library to link against instead of SQLite. This feature is mutually exclusive with bundled.
  • hooks for Commit, Rollback and Data Change notification callbacks.
  • unlock_notify for Unlock notification.
  • vtab for virtual table support (allows you to write virtual table implementations in Rust). Currently, only read-only virtual tables are supported.
  • csvtab, CSV virtual table written in Rust.
  • array, The rarray() Table-Valued Function.
  • 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.
  • uuid allows storing and retrieving Uuid values from the uuid crate using blobs.
  • session, Session module extension. Requires buildtime_bindgen feature.

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 find a SQLite library that already exists on your system using pkg-config, or a Vcpkg installation for MSVC ABI builds.

You can adjust this behavior in a number of ways:

  • If you use the bundled feature, libsqlite3-sys will use the cc crate to compile SQLite from source and link against that. This source is embedded in the libsqlite3-sys crate and is currently SQLite 3.34.0 (as of rusqlite 0.24.1 / libsqlite3-sys 0.21.0). This is probably the simplest solution to any build problems. You can enable this by adding the following in your Cargo.toml file:
    [dependencies.rusqlite]
    version = "0.24.2"
    features = ["bundled"]
  • You can set the SQLITE3_LIB_DIR to point to directory containing the SQLite library.
  • Installing the sqlite3 development packages will usually be all that is required, but the build helpers for pkg-config and vcpkg have some additional configuration options. The default when using vcpkg is to dynamically link, which must be enabled by setting VCPKGRS_DYNAMIC=1 environment variable before build. vcpkg install sqlite3:x64-windows will install the required library.

Binding generation

We use bindgen to generate the Rust declarations from SQLite's C header file. bindgen recommends 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_23 - SQLite 3.6.23 bindings
  • min_sqlite_version_3_7_7 - SQLite 3.7.7 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.

If you enable the modern_sqlite feature, we'll use the bindings we would have included with the bundled build. You generally should have buildtime_bindgen enabled if you turn this on, as otherwise you'll need to keep the version of SQLite you link with in sync with what rusqlite would have bundled, (usually the most recent release of sqlite). Failing to do this will cause a runtime error.

Contributing

Rusqlite has many features, and many of them impact the build configuration in incompatible ways. This is unfortunate, and makes testing changes hard.

To help here: you generally should ensure that you run tests/lint for --features bundled, and --features bundled-full session buildtime_bindgen.

If running bindgen is problematic for you, --features bundled-full enables bundled and all features which don't require binding generation, and can be used instead.

Checklist

  • Run cargo fmt to ensure your Rust code is correctly formatted.
  • Ensure cargo clippy --all-targets --workspace --features bundled passes without warnings.
  • Ensure cargo test --all-targets --workspace --features bundled-full session buildtime_bindgen reports no failures.
  • Ensure cargo test --all-targets --workspace --features bundled reports no failures.
  • Ensure cargo test --all-targets --workspace --features bundled-full session buildtime_bindgen reports no failures.

Author

Rusqlite is the product of hard work by a number of people. A list is available here: https://github.com/rusqlite/rusqlite/graphs/contributors

Community

Currently there's a gitter channel set up for rusqlite here.

License

Rusqlite is available under the MIT license. See the LICENSE file for more info.

rusqlite's People

Contributors

cactorium avatar chamakits avatar derekdreery avatar dubiousjim avatar dushistov avatar edelangh avatar emilio avatar gentoo90 avatar gwenn avatar huonw avatar hydhknn avatar jgallagher avatar jrandall avatar kamilaborowska avatar kixunil avatar kornelski avatar lgarczyn avatar marcusklaas avatar mcgoo avatar mqudsi avatar pfernie avatar rainhead avatar sbstp avatar sgrif avatar technic avatar thomcc avatar timmmm avatar tjeukayim avatar traviscross avatar twistedfall avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.