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 URL, as described by SQLite.

This type also implements FromStr so you can parse it from a string containing a connection URL and then further adjust options if necessary (see example below).

URLDescription
sqlite::memory:Open an in-memory database.
sqlite:data.dbOpen the file data.db in the current directory.
sqlite://data.dbOpen the file data.db in the current directory.
sqlite:///data.dbOpen the file data.db from the root (/) directory.
sqlite://data.db?mode=roOpen the file data.db for read-only access.

§Example

use sqlx::ConnectOptions;
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 get_filename(self) -> Cow<'static, Path>

Gets the current name of the database file.

source

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

Set the enforcement of foreign key constraints.

SQLx chooses to enable this by default so that foreign keys function as expected, compared to other database flavors.

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.

Journal modes are ephemeral per connection, with the exception of the Write-Ahead Log (WAL) mode.

A database created in WAL mode retains the setting and will apply it to all connections opened against it that don’t set a journal_mode.

Opening a connection to a database created in WAL mode with a different journal_mode will erase the setting on the database, requiring an exclusive lock to do so. You may get a database is locked (corresponding to SQLITE_BUSY) error if another connection is accessing the database file at the same time.

SQLx does not set a journal mode by default, to avoid unintentionally changing a database into or out of WAL mode.

The default journal mode for non-WAL databases is DELETE, or MEMORY for in-memory databases.

For consistency, any commands in sqlx-cli which create a SQLite database will create it in WAL mode.

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.

For existing databases, a change to this value does not take effect unless a VACUUM command is executed.

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.

For existing databases, a change to this value does not take effect unless a VACUUM command is executed. However, it cannot be changed in WAL mode.

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 A<B then B>A. 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 corresponding to using OPEN_NOMUTEX. If set to 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

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

Set the maximum number of rows to buffer back to the calling task when a query is executed.

If the calling task cannot keep up, backpressure will be applied to the worker thread in order to limit CPU and memory usage.

source

pub fn vfs(self, vfs_name: impl Into<Cow<'static, str>>) -> Self

Sets the vfs parameter of the database connection.

The default value is empty, and sqlite will use the default VFS object depending on the operating system.

source

pub fn extension(self, extension_name: impl Into<Cow<'static, str>>) -> Self

Load an extension at run-time when the database connection is established, using the default entry point.

Most common SQLite extensions can be loaded using this method, for extensions where you need to specify the entry point, use extension_with_entrypoint instead.

Multiple extensions can be loaded by calling the method repeatedly on the options struct, they will be loaded in the order they are added.

let options = SqliteConnectOptions::from_str("sqlite://data.db")?
    .extension("vsv")
    .extension("mod_spatialite");
source

pub fn extension_with_entrypoint( self, extension_name: impl Into<Cow<'static, str>>, entry_point: impl Into<Cow<'static, str>> ) -> Self

Load an extension with a specified entry point.

Useful when using non-standard extensions, or when developing your own, the second argument specifies where SQLite should expect to find the extension init routine.

source

pub fn optimize_on_close( self, enabled: bool, analysis_limit: impl Into<Option<u32>> ) -> Self

Execute PRAGMA optimize; on the SQLite connection before closing.

The SQLite manual recommends using this for long-lived databases.

This will collect and store statistics about the layout of data in your tables to help the query planner make better decisions. Over the connection’s lifetime, the query planner will make notes about which tables could use up-to-date statistics so this command doesn’t have to scan the whole database every time. Thus, the best time to execute this is on connection close.

analysis_limit sets a soft limit on the maximum number of rows to scan per index. It is equivalent to setting Self::analysis_limit but only takes effect for the PRAGMA optimize; call and does not affect the behavior of any ANALYZE statements made during the connection’s lifetime.

If not None, the analysis_limit here overrides the global analysis_limit setting, but only for the PRAGMA optimize; call.

Not enabled by default.

See the SQLite manual for details.

source

pub fn analysis_limit(self, limit: impl Into<Option<u32>>) -> Self

Set a soft limit on the number of rows that ANALYZE touches per index.

This also affects PRAGMA optimize which is set by Self::optimize_on_close.

The value recommended by SQLite is 400. There is no default.

See the SQLite manual for details.

Trait Implementations§

source§

impl Clone for SqliteConnectOptions

source§

fn clone(&self) -> SqliteConnectOptions

Returns a copy of the value. Read more
1.0.0 · source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
source§

impl ConnectOptions for SqliteConnectOptions

§

type Connection = SqliteConnection

source§

fn from_url(url: &Url) -> Result<Self, Error>

Parse the ConnectOptions from a URL.
source§

fn to_url_lossy(&self) -> Url

Get a connection URL that may be used to connect to the same database as this ConnectOptions. Read more
source§

fn connect(&self) -> BoxFuture<'_, Result<Self::Connection, Error>>
where Self::Connection: Sized,

Establish a new database connection with the options specified by self.
source§

fn log_statements(self, level: LevelFilter) -> Self

Log executed statements with the specified level
source§

fn log_slow_statements(self, level: LevelFilter, duration: Duration) -> Self

Log executed statements with a duration above the specified duration at the specified level.
source§

fn disable_statement_logging(self) -> Self

Entirely disables statement logging (both slow and regular).
source§

impl Debug for SqliteConnectOptions

source§

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

Formats the value using the given formatter. Read more
source§

impl Default for SqliteConnectOptions

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl FromStr for SqliteConnectOptions

§

type Err = Error

The associated error which can be returned from parsing.
source§

fn from_str(url: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
source§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more