Struct Connection

Source

pub struct Connection { /* private fields */ }

Expand description

A sqlite database connection.

Connections are not thread-safe objects.

§Examples

Opening a connection to a filesystem path:

use sqlite_ll::Connection;

let c = Connection::open("database.db")?;
c.execute("CREATE TABLE test (id INTEGER);")?;

Opening an in-memory database:

use sqlite_ll::Connection;

let c = Connection::open_memory()?;
c.execute("CREATE TABLE test (id INTEGER);")?;

Implementations§

Source §

impl Connection

Source

pub fn open(path: impl AsRef<Path>) -> Result<Connection>

Available on crate feature std only.

Open a database to the given path.

Note that it is possible to open an in-memory database by passing ":memory:" here, this call might require allocating depending on the platform, so it should be avoided in favor of using memory. To avoid allocating for regular paths, you can use open_c_str, however you are responsible for ensuring the c-string is a valid path.

This is the same as calling OpenOptions::new().read_write().create().open(path).

Source

pub fn open_c_str(name: &CStr) -> Result<Connection>

Open a database connection with a raw c-string.

This can be used to open in-memory databases by passing c":memory:" or a regular open call with a filesystem path like c"/path/to/database.sql".

This is the same as calling OpenOptions::new().read_write().create().open_c_str(name).

Source

pub fn open_memory() -> Result<Connection>

Open an in-memory database.

This is the same as calling OpenOptions::new().read_write().create().open_memory().

Source

pub fn execute(&self, stmt: impl AsRef<str>) -> Result<()>

Execute a statement without processing the resulting rows if any.

Source

pub fn prepare(&self, stmt: impl AsRef<str>) -> Result<Statement>

Build a prepared statement.

This is the same as calling prepare_with with Prepare::EMPTY.

The database connection will be kept open for the lifetime of this statement.

§Errors

If the prepare call contains multiple statements, it will error. To execute multiple statements, use execute instead.

use sqlite_ll::{Connection, Code};

let c = Connection::open_memory()?;

let e = c.prepare(
    "
    CREATE TABLE test (id INTEGER) /* test */;
    INSERT INTO test (id) VALUES (1);
    "
).unwrap_err();

assert_eq!(e.code(), Code::ERROR);

§Examples

use sqlite_ll::{Connection, State, Prepare};

let c = Connection::open_memory()?;
c.execute("CREATE TABLE test (id INTEGER);")?;

let mut insert_stmt = c.prepare("INSERT INTO test (id) VALUES (?);")?;
let mut query_stmt = c.prepare("SELECT id FROM test;")?;

drop(c);

insert_stmt.reset()?;
insert_stmt.bind(1, 42)?;
assert_eq!(insert_stmt.step()?, State::Done);

query_stmt.reset()?;

while let State::Row = query_stmt.step()? {
    let id: i64 = query_stmt.read(0)?;
    assert_eq!(id, 42);
}

Source

pub fn prepare_with( &self, stmt: impl AsRef<str>, flags: Prepare, ) -> Result<Statement>

Build a prepared statement with custom flags.

For long-running statements it is recommended that they have the Prepare::PERSISTENT flag set.

The database connection will be kept open for the lifetime of this statement.

§Errors

If the prepare call contains multiple statements, it will error. To execute multiple statements, use execute instead.

use sqlite_ll::{Connection, Code, Prepare};

let c = Connection::open_memory()?;

let e = c.prepare_with(
    "
    CREATE TABLE test (id INTEGER) /* test */;
    INSERT INTO test (id) VALUES (1);
    ",
    Prepare::PERSISTENT
).unwrap_err();
assert_eq!(e.code(), Code::ERROR);

§Examples

use sqlite_ll::{Connection, State, Prepare};

let c = Connection::open_memory()?;
c.execute("CREATE TABLE test (id INTEGER);")?;

let mut insert_stmt = c.prepare_with("INSERT INTO test (id) VALUES (?);", Prepare::PERSISTENT)?;
let mut query_stmt = c.prepare_with("SELECT id FROM test;", Prepare::PERSISTENT)?;

drop(c);

/* .. */

insert_stmt.reset()?;
insert_stmt.bind(1, 42)?;
assert_eq!(insert_stmt.step()?, State::Done);

query_stmt.reset()?;

while let State::Row = query_stmt.step()? {
    let id: i64 = query_stmt.read(0)?;
    assert_eq!(id, 42);
}

Source

pub fn change_count(&self) -> usize

Return the number of rows inserted, updated, or deleted by the most recent INSERT, UPDATE, or DELETE statement.

Source

pub fn total_change_count(&self) -> usize

Return the total number of rows inserted, updated, and deleted by all INSERT, UPDATE, and DELETE statements since the connection was opened.

Source

pub fn set_busy_handler<F>(&mut self, callback: F) -> Result<()>
where F: FnMut(usize) -> bool + Send + 'static,

Set a callback for handling busy events.

The callback is triggered when the database cannot perform an operation due to processing of some other request. If the callback returns true, the operation will be repeated.

Source