Struct AsyncSqliteIo 

pub struct AsyncSqliteIo<S: AsyncConnectionState> { /* private fields */ }

Async interface for page-level SQLite database access.

This struct wraps the blocking SqliteIo and executes all blocking SQLite operations via tokio::task::spawn_blocking.

Important Notes

• The connection is opened in-memory, and the actual database file is attached
• All page operations use the ‘target’ schema name
• The connection is configured with special permissions for page-level access

Typestate Pattern

This connection uses a typestate pattern. When you start a transaction with transaction, the connection moves to the AsyncInTransaction state. You must call commit() or rollback() to return to the normal state.

Implementations

impl AsyncSqliteIo<AsyncNormal>

pub async fn open(uri: &str) -> Result<Self, Error>

Opens a database for page-level access asynchronously.

This creates an in-memory SQLite connection and attaches the database using the provided URI. The URI can be a simple path or include query parameters like ?vfs=reverb.

Arguments

• uri - URI string for the database. Can be:
  • A simple path: /path/to/db.sqlite
  • A file URI: file:/path/to/db.sqlite
  • A URI with parameters: file:/path/to/db.sqlite?vfs=reverb

Errors

Returns an error if:

• The database path is invalid
• The database cannot be opened or attached
• The specified VFS is not registered
• Required database configurations cannot be set

pub async fn transaction( self, transaction_type: TransactionType, ) -> Result<AsyncSqliteIo<AsyncInTransaction>, Error>

Starts a new async transaction for page modifications.

This method consumes the connection and returns it in transaction mode. You must call commit() or rollback() on the returned connection to get back to normal mode.

Arguments

• transaction_type - The type of transaction to begin. Use TransactionType::Immediate (the default) for write operations to avoid SQLITE_BUSY errors.

Errors

Returns an error if the transaction cannot be started.

Example

use sqlite_pages::{AsyncSqliteIo, TransactionType};

// Create a test database
let tempdir = tempfile::tempdir()?;
let db_path = tempdir.path().join("test.db");
rusqlite::Connection::open(&db_path)?.execute(
    "CREATE TABLE test (id INTEGER PRIMARY KEY)",
    [],
)?;

let db = AsyncSqliteIo::open(&db_path.to_string_lossy()).await?;
let tx = db.transaction(TransactionType::Immediate).await?;

// Can await between operations
let page = tx.get_page_data(1).await?;
tx.set_page_data(1, page.data()).await?;
let db = tx.commit().await?;  // Returns connection back to normal mode

pub async fn page_map<R, F>(&self, range: R, fun: F) -> Result<(), Error>

where R: RangeBounds<usize> + Send + 'static, F: FnMut(usize, &[u8]) + Send + 'static,

Maps a function over database pages in the specified range asynchronously.

Page numbers are 1-based (the first page is page 1, not page 0).

Arguments

• range - A range of page numbers (1-based) to process
• fun - A function that receives the page number (1-based) and page data for each page

Errors

Returns an error if:

• The range is invalid (start > end)
• The database cannot be queried
• Page data cannot be read

pub async fn page_count(&self) -> Result<usize, Error>

Returns the number of pages in the database.

Errors

Returns an error if the page count cannot be retrieved.

pub async fn with_connection<F, R>(&self, f: F) -> Result<R, Error>

where F: FnOnce(&Connection) -> R + Send + 'static, R: Send + 'static,

Executes a closure with access to the underlying SqliteIo connection.

This method provides synchronous access to the rusqlite::Connection for operations that require direct SQL access, such as diagnostic queries, test setup, or arbitrary SQL execution.

The closure runs inside spawn_blocking to avoid blocking the async runtime.

Arguments

• f - A closure that receives a reference to the SqliteIo and returns a value.

Errors

Returns an error if the inner connection cannot be accessed or if the spawned task fails.

Example

use sqlite_pages::AsyncSqliteIo;

let db = AsyncSqliteIo::open(&db_path.to_string_lossy()).await?;

// Execute arbitrary SQL via the connection
let count: i64 = db.with_connection(|conn| {
    conn.query_row("SELECT COUNT(*) FROM sqlite_master", [], |row| row.get(0))
        .unwrap()
}).await?;

impl AsyncSqliteIo<AsyncInTransaction>

pub async fn set_page_data( &self, page_number: usize, data: &[u8], ) -> Result<(), Error>

Sets the data for a specific page in the database.

Arguments

• page_number - The page number (1-based: first page is 1)
• data - The raw page data

Errors

Returns an error if the page data cannot be written to the database.

pub async fn get_page_data(&self, page_number: usize) -> Result<Page, Error>

Retrieves the data for a specific page from the database.

Arguments

• page_number - The page number (1-based: first page is 1)

Errors

Returns an error if the page cannot be read from the database.

pub async fn page_map<R, F>(&self, range: R, fun: F) -> Result<(), Error>

where R: RangeBounds<usize> + Send + 'static, F: FnMut(usize, &[u8]) + Send + 'static,

Maps a function over database pages in the specified range asynchronously.

Page numbers are 1-based (the first page is page 1, not page 0).

Arguments

• range - A range of page numbers (1-based) to process
• fun - A function that receives the page number (1-based) and page data for each page

Errors

Returns an error if the range is invalid or pages cannot be read.

pub async fn with_connection<F, R>(&self, f: F) -> Result<R, Error>

where F: FnOnce(&Connection) -> R + Send + 'static, R: Send + 'static,

Executes a closure with access to the underlying rusqlite::Connection.

This method provides synchronous access to the rusqlite::Connection for operations that require direct SQL access, such as diagnostic queries, test setup, or arbitrary SQL execution.

The closure runs inside spawn_blocking to avoid blocking the async runtime.

Arguments

• f - A closure that receives a reference to the connection and returns a value.

Errors

Returns an error if the inner connection cannot be accessed or if the spawned task fails.

pub async fn commit(self) -> Result<AsyncSqliteIo<AsyncNormal>, Error>

Commits the transaction, persisting all changes to the database.

Returns the connection back to normal mode.

Errors

Returns an error if the transaction cannot be committed.

pub async fn rollback(self) -> Result<AsyncSqliteIo<AsyncNormal>, Error>

Rolls back the transaction, discarding all changes.

Returns the connection back to normal mode.

Errors

Returns an error if the rollback fails.