Struct sqlx_core::sqlite::SqliteConnectOptions

source · [−]

pub struct SqliteConnectOptions { /* private fields */ }

Expand description

Options and flags which can be used to configure a SQLite connection.

A value of SqliteConnectOptions can be parsed from a connection URI, as described by SQLite.

URI	Description
`sqlite::memory:`	Open an in-memory database.
`sqlite:data.db`	Open the file `data.db` in the current directory.
`sqlite://data.db`	Open the file `data.db` in the current directory.
`sqlite:///data.db`	Open the file `data.db` from the root (`/`) directory.
`sqlite://data.db?mode=ro`	Open the file `data.db` for read-only access.

Example

use sqlx::sqlite::{SqliteConnectOptions, SqliteJournalMode};
use std::str::FromStr;

let conn = SqliteConnectOptions::from_str("sqlite://data.db")?
    .journal_mode(SqliteJournalMode::Wal)
    .read_only(true)
    .connect().await?;

Implementations

source

impl SqliteConnectOptions

source

pub fn new() -> Self

Construct Self with default options.

See the source of this method for the current defaults.

source

pub fn filename(self, filename: impl AsRef<Path>) -> Self

Sets the name of the database file.

source

pub fn foreign_keys(self, on: bool) -> Self

Set the enforcement of foreign key constraints.

By default, this is enabled.

source

pub fn shared_cache(self, on: bool) -> Self

Set the SQLITE_OPEN_SHAREDCACHE flag.

By default, this is disabled.

source

pub fn journal_mode(self, mode: SqliteJournalMode) -> Self

Sets the journal mode for the database connection.

The default journal mode is WAL. For most use cases this can be significantly faster but there are disadvantages.

source

pub fn locking_mode(self, mode: SqliteLockingMode) -> Self

Sets the locking mode for the database connection.

The default locking mode is NORMAL.

source

pub fn read_only(self, read_only: bool) -> Self

Sets the access mode to open the database for read-only access.

source

pub fn create_if_missing(self, create: bool) -> Self

Sets the access mode to create the database file if the file does not exist.

By default, a new file will not be created if one is not found.

source

pub fn statement_cache_capacity(self, capacity: usize) -> Self

Sets the capacity of the connection’s statement cache in a number of stored distinct statements. Caching is handled using LRU, meaning when the amount of queries hits the defined limit, the oldest statement will get dropped.

The default cache capacity is 100 statements.

source

pub fn busy_timeout(self, timeout: Duration) -> Self

Sets a timeout value to wait when the database is locked, before returning a busy timeout error.

The default busy timeout is 5 seconds.

source

pub fn synchronous(self, synchronous: SqliteSynchronous) -> Self

Sets the synchronous setting for the database connection.

The default synchronous settings is FULL. However, if durability is not a concern, then NORMAL is normally all one needs in WAL mode.

source

pub fn auto_vacuum(self, auto_vacuum: SqliteAutoVacuum) -> Self

Sets the auto_vacuum setting for the database connection.

The default auto_vacuum setting is NONE.

source

pub fn page_size(self, page_size: u32) -> Self

Sets the page_size setting for the database connection.

The default page_size setting is 4096.

source

pub fn pragma<K, V>(self, key: K, value: V) -> Self where
K: Into<Cow<'static, str>>,
V: Into<Cow<'static, str>>,

Sets custom initial pragma for the database connection.

source

pub fn collation<N, F>(self, name: N, collate: F) -> Self where
N: Into<Arc<str>>,
F: Fn(&str, &str) -> Ordering + Send + Sync + 'static,

Add a custom collation for comparing strings in SQL.

If a collation with the same name already exists, it will be replaced.

See sqlite3_create_collation() for details.

Note this excerpt:

The collating function must obey the following properties for all strings A, B, and C:

If A==B then B==A.
If A==B and B==C then A==C.
If AA.
If A<B and B<C then A<C.

If a collating function fails any of the above constraints and that collating function is registered and used, then the behavior of SQLite is undefined.

source

pub fn immutable(self, immutable: bool) -> Self

Set to true to signal to SQLite that the database file is on read-only media.

If enabled, SQLite assumes the database file cannot be modified, even by higher privileged processes, and so disables locking and change detection. This is intended to improve performance but can produce incorrect query results or errors if the file does change.

Note that this is different from the SQLITE_OPEN_READONLY flag set by .read_only(), though the documentation suggests that this does imply SQLITE_OPEN_READONLY.

See sqlite3_open (subheading “URI Filenames”) for details.

source

pub fn serialized(self, serialized: bool) -> Self

Sets the threading mode for the database connection.

The default setting is false corersponding to using OPEN_NOMUTEX, if true then OPEN_FULLMUTEX.

See open for more details.

Note

Setting this to true may help if you are getting access violation errors or segmentation faults, but will also incur a significant performance penalty. You should leave this set to false if at all possible.

If you do end up needing to set this to true for some reason, please open an issue as this may indicate a concurrency bug in SQLx. Please provide clear instructions for reproducing the issue, including a sample database schema if applicable.

source

pub fn thread_name(
self,
generator: impl Fn(u64) -> String + Send + Sync + 'static
) -> Self

Provide a callback to generate the name of the background worker thread.

The value passed to the callback is an auto-incremented integer for use as the thread ID.

source

pub fn command_buffer_size(self, size: usize) -> Self

Set the maximum number of commands to buffer for the worker thread before backpressure is applied.

Given that most commands sent to the worker thread involve waiting for a result, the command channel is unlikely to fill up unless a lot queries are executed in a short period but cancelled before their full resultsets are returned.

source