Crate tokio_rusqlite

Asynchronous handle for rusqlite library.

Guide

This library provides Connection struct. Connection struct is a handle to call functions in background thread and can be cloned cheaply. Connection::call method calls provided function in the background thread and returns its result asynchronously.

Design

A thread is spawned for each opened connection handle. When call method is called: provided function is boxed, sent to the thread through mpsc channel and executed. Return value is then sent by oneshot channel from the thread and then returned from function.

Example

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

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

#[tokio::main]
async fn main() -> Result<()> {
    let conn = Connection::open_in_memory().await?;

    let people = conn
        .call(|conn| {
            conn.execute(
                "CREATE TABLE person (
                    id    INTEGER PRIMARY KEY,
                    name  TEXT NOT NULL,
                    data  BLOB
                )",
                [],
            )?;

            let steven = Person {
                id: 1,
                name: "Steven".to_string(),
                data: None,
            };

            conn.execute(
                "INSERT INTO person (name, data) VALUES (?1, ?2)",
                params![steven.name, steven.data],
            )?;

            let mut stmt = conn.prepare("SELECT id, name, data FROM person")?;
            let people = stmt
                .query_map([], |row| {
                    Ok(Person {
                        id: row.get(0)?,
                        name: row.get(1)?,
                        data: row.get(2)?,
                    })
                })?
                .collect::<std::result::Result<Vec<Person>, rusqlite::Error>>()?;

            Ok(people)
        })
        .await?;

    for person in people {
        println!("Found person {:?}", person);
    }

    Ok(())
}

Modules

• config
  Configure database connections
• ffi
• types
  Traits dealing with SQLite data types.

Macros

• named_params
  A macro making it more convenient to pass lists of named parameters as a &[(&str, &dyn ToSql)].
• params
  A macro making it more convenient to longer lists of parameters as a &[&dyn ToSql].

Structs

• AndThenRows
  An iterator over the mapped resulting rows of a query, with an Error type unifying with Error.
• Batch
  Batch iterator
• CachedStatement
  Cacheable statement.
• Connection
  A handle to call functions in background thread.
• InterruptHandle
  Allows interrupting a long-running computation.
• Map
  F is used to transform the streaming iterator into a fallible iterator.
• MappedRows
  An iterator over the mapped resulting rows of a query.
• OpenFlags
  Flags for opening SQLite database connections. See sqlite3_open_v2 for details.
• ParamsFromIter
  Adapter type which allows any iterator over ToSql values to implement Params.
• PrepFlags
  Prepare flags. See sqlite3_prepare_v3 for details.
• Row
  A single result row of a query.
• Rows
  An handle for the resulting rows of a query.
• Savepoint
  Represents a savepoint on a database connection.
• Statement
  A prepared statement.
• Transaction
  Represents a transaction on a database connection.

Enums

• DatabaseName
  Name for a database within a SQLite connection.
• DropBehavior
  Options for how a Transaction or Savepoint should behave when it is dropped.
• Error
  Represents the errors specific for this library.
• ErrorCode
  Error Codes
• StatementStatus
  Prepared statement status counters.
• TransactionBehavior
  Options for transaction behavior. See BEGIN TRANSACTION for details.

Constants

• MAIN_DB
  Shorthand for DatabaseName::Main.
• TEMP_DB
  Shorthand for DatabaseName::Temp.

Traits

• OptionalExtension
  See the method documentation.
• Params
  Trait used for sets of parameter passed into SQL statements/queries.
• RowIndex
  A trait implemented by types that can index into columns of a row.
• ToSql
  A trait for types that can be converted into SQLite values. Returns Error::ToSqlConversionFailure if the conversion fails.

Functions

• bypass_sqlite_initialization^⚠
  rusqlite’s check for a safe SQLite threading mode requires SQLite 3.7.0 or later. If you are running against a SQLite older than that, rusqlite attempts to ensure safety by performing configuration and initialization of SQLite itself the first time you attempt to open a connection. By default, rusqlite panics if that initialization fails, since that could mean SQLite has been initialized in single-thread mode.
• params_from_iter
  Constructor function for a ParamsFromIter. See its documentation for more.
• to_sqlite_error^⚠
  Transform Rust error to SQLite error (message and code).
• version
  Returns the SQLite version as a string; e.g., "3.16.2" for version 3.16.2.
• version_number
  Returns the SQLite version as an integer; e.g., 3016002 for version 3.16.2.

Type Aliases

• Result
  The result returned on method calls in this crate.