Struct SqliteConnection

pub struct SqliteConnection { /* private fields */ }

Available on crate feature _sqlite only.

A connection to an open Sqlite database.

Because SQLite is an in-process database accessed by blocking API calls, SQLx uses a background thread and communicates with it via channels to allow non-blocking access to the database.

Dropping this struct will signal the worker thread to quit and close the database, though if an error occurs there is no way to pass it back to the user this way.

You can explicitly call .close() to ensure the database is closed successfully or get an error otherwise.

Implementations

impl SqliteConnection

pub async fn serialize( &mut self, schema: Option<&str>, ) -> Result<SqliteOwnedBuf, Error>

Serialize the given SQLite database schema using sqlite3_serialize().

The returned buffer is a SQLite managed allocation containing the equivalent data as writing the database to disk. It is freed on-drop.

To serialize the primary, unqualified schema (main), pass None for the schema name.

Errors

• Error::InvalidArgument if the schema name contains a zero/NUL byte (\0).
• Error::Database if the schema does not exist or another error occurs.

pub async fn deserialize( &mut self, schema: Option<&str>, data: SqliteOwnedBuf, read_only: bool, ) -> Result<(), Error>

Deserialize a SQLite database from a buffer into the specified schema using sqlite3_deserialize().

The given schema will be disconnected and re-connected as an in-memory database backed by data, which should be the serialized form of a database previously returned by a call to Self::serialize(), documented as being equivalent to the contents of the database file on disk.

An error will be returned if a schema with the given name is not already attached.
You can use ATTACH ':memory' as "<schema name>" to create an empty schema first.

Pass None to deserialize to the primary, unqualified schema (main).

The SQLite connection will take ownership of data and will free it when the connection is closed or the schema is detached (SQLITE_DESERIALIZE_FREEONCLOSE).

If read_only is true, the schema is opened as read-only (SQLITE_DESERIALIZE_READONLY).
If false, the schema is marked as resizable (SQLITE_DESERIALIZE_RESIZABLE).

If the database is in WAL mode, an error is returned. See sqlite3_deserialize() for details.

Errors

• Error::InvalidArgument if the schema name contains a zero/NUL byte (\0).
• Error::Database if an error occurs during deserialization.

impl SqliteConnection

pub async fn lock_handle(&mut self) -> Result<LockedSqliteHandle<'_>, Error>

Lock the SQLite database handle out from the worker thread so direct SQLite API calls can be made safely.

Returns an error if the worker thread crashed.

Trait Implementations

impl<'c> Acquire<'c> for &'c mut SqliteConnection

type Database = Sqlite

type Connection = &'c mut <Sqlite as Database>::Connection

fn acquire( self, ) -> Pin<Box<dyn Future<Output = Result<<&'c mut SqliteConnection as Acquire<'c>>::Connection, Error>> + Send + 'c>>

fn begin( self, ) -> Pin<Box<dyn Future<Output = Result<Transaction<'c, Sqlite>, Error>> + Send + 'c>>

impl AnyConnectionBackend for SqliteConnection

fn name(&self) -> &str

The backend name.

fn close( self: Box<SqliteConnection>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>

Explicitly close this database connection.

fn ping( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Checks if a connection to the database is still valid.

fn begin( &mut self, statement: Option<Cow<'static, str>>, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Begin a new transaction or establish a savepoint within the active transaction.

fn commit( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

fn rollback( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

fn start_rollback(&mut self)

fn get_transaction_depth(&self) -> usize

Returns the current transaction depth.

fn shrink_buffers(&mut self)

Forward to Connection::shrink_buffers().

fn as_migrate(&mut self) -> Result<&mut (dyn Migrate + Send + 'static), Error>

fn fetch_many<'q>( &'q mut self, query: &'q str, persistent: bool, arguments: Option<AnyArguments<'q>>, ) -> Pin<Box<dyn Stream<Item = Result<Either<AnyQueryResult, AnyRow>, Error>> + Send + 'q>>

fn fetch_optional<'q>( &'q mut self, query: &'q str, persistent: bool, arguments: Option<AnyArguments<'q>>, ) -> Pin<Box<dyn Future<Output = Result<Option<AnyRow>, Error>> + Send + 'q>>

fn prepare_with<'c, 'q>( &'c mut self, sql: &'q str, _parameters: &[AnyTypeInfo], ) -> Pin<Box<dyn Future<Output = Result<AnyStatement<'q>, Error>> + Send + 'c>>

where 'q: 'c,

fn describe<'q>( &'q mut self, sql: &'q str, ) -> Pin<Box<dyn Future<Output = Result<Describe<Any>, Error>> + Send + 'q>>

fn is_in_transaction(&self) -> bool

Checks if the connection is currently in a transaction.

fn cached_statements_size(&self) -> usize

The number of statements currently cached in the connection.

fn clear_cached_statements( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Removes all statements from the cache, closing them on the server if needed.

impl Connection for SqliteConnection

fn ping( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Ensure the background worker thread is alive and accepting commands.

type Database = Sqlite

type Options = SqliteConnectOptions

fn close(self) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>>

Explicitly close this database connection.

fn begin( &mut self, ) -> Pin<Box<dyn Future<Output = Result<Transaction<'_, <SqliteConnection as Connection>::Database>, Error>> + Send + '_>>

where SqliteConnection: Sized,

Begin a new transaction or establish a savepoint within the active transaction.

fn begin_with( &mut self, statement: impl Into<Cow<'static, str>>, ) -> Pin<Box<dyn Future<Output = Result<Transaction<'_, <SqliteConnection as Connection>::Database>, Error>> + Send + '_>>

where SqliteConnection: Sized,

Begin a new transaction with a custom statement.

fn cached_statements_size(&self) -> usize

The number of statements currently cached in the connection.

fn clear_cached_statements( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send + '_>>

Removes all statements from the cache, closing them on the server if needed.

fn shrink_buffers(&mut self)

Restore any buffers in the connection to their default capacity, if possible.

fn is_in_transaction(&self) -> bool

Returns true if the connection is currently in a transaction.

fn transaction<'a, F, R, E>( &'a mut self, callback: F, ) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'a>>

where F: for<'c> FnOnce(&'c mut Transaction<'_, Self::Database>) -> Pin<Box<dyn Future<Output = Result<R, E>> + Send + 'c>> + 'a + for<'c> Send + for<'c> Sync, Self: Sized, R: Send, E: From<Error> + Send,

Execute the function inside a transaction.

fn connect( url: &str, ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send>>

where Self: Sized,

Establish a new database connection.

fn connect_with( options: &Self::Options, ) -> Pin<Box<dyn Future<Output = Result<Self, Error>> + Send + '_>>

where Self: Sized,

Establish a new database connection with the provided options.

impl Debug for SqliteConnection

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<'c> Executor<'c> for &'c mut SqliteConnection

type Database = Sqlite

fn fetch_many<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<Either<SqliteQueryResult, SqliteRow>, Error>> + Send + 'e>>

where 'c: 'e, 'q: 'e, E: Execute<'q, <&'c mut SqliteConnection as Executor<'c>>::Database> + 'q,

Execute multiple queries and return the generated results as a stream from each query, in a stream.

fn fetch_optional<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<Option<SqliteRow>, Error>> + Send + 'e>>

where 'c: 'e, 'q: 'e, E: Execute<'q, <&'c mut SqliteConnection as Executor<'c>>::Database> + 'q,

Execute the query and returns at most one row.

fn prepare_with<'e, 'q>( self, sql: &'q str, _parameters: &[SqliteTypeInfo], ) -> Pin<Box<dyn Future<Output = Result<SqliteStatement<'q>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e,

Prepare the SQL query, with parameter type information, to inspect the type information about its parameters and results.

fn execute<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return the total number of rows affected.

fn execute_many<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::QueryResult, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute multiple queries and return the rows affected from each query, in a stream.

fn fetch<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Stream<Item = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return the generated results as a stream.

fn fetch_all<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<Vec<<Self::Database as Database>::Row>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and return all the generated results, collected into a Vec.

fn fetch_one<'e, 'q, E>( self, query: E, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Row, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e, E: 'q + Execute<'q, Self::Database>,

Execute the query and returns exactly one row.

fn prepare<'e, 'q>( self, query: &'q str, ) -> Pin<Box<dyn Future<Output = Result<<Self::Database as Database>::Statement<'q>, Error>> + Send + 'e>>

where 'q: 'e, 'c: 'e,

Prepare the SQL query to inspect the type information of its parameters and results.

impl Migrate for SqliteConnection

fn ensure_migrations_table( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), MigrateError>> + Send + '_>>

fn dirty_version( &mut self, ) -> Pin<Box<dyn Future<Output = Result<Option<i64>, MigrateError>> + Send + '_>>

fn list_applied_migrations( &mut self, ) -> Pin<Box<dyn Future<Output = Result<Vec<AppliedMigration>, MigrateError>> + Send + '_>>

fn lock( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), MigrateError>> + Send + '_>>

fn unlock( &mut self, ) -> Pin<Box<dyn Future<Output = Result<(), MigrateError>> + Send + '_>>

fn apply<'e, 'm>( &'e mut self, migration: &'m Migration, ) -> Pin<Box<dyn Future<Output = Result<Duration, MigrateError>> + Send + 'm>>

where 'e: 'm,

fn revert<'e, 'm>( &'e mut self, migration: &'m Migration, ) -> Pin<Box<dyn Future<Output = Result<Duration, MigrateError>> + Send + 'm>>

where 'e: 'm,