Struct sqlx::sqlite::SqliteConnectOptions
source · pub struct SqliteConnectOptions { /* private fields */ }
sqlite
only.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.
URL | 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
impl SqliteConnectOptions
sourcepub fn new() -> SqliteConnectOptions
pub fn new() -> SqliteConnectOptions
Construct Self
with default options.
See the source of this method for the current defaults.
sourcepub fn filename(self, filename: impl AsRef<Path>) -> SqliteConnectOptions
pub fn filename(self, filename: impl AsRef<Path>) -> SqliteConnectOptions
Sets the name of the database file.
sourcepub fn foreign_keys(self, on: bool) -> SqliteConnectOptions
pub fn foreign_keys(self, on: bool) -> SqliteConnectOptions
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.
Set the SQLITE_OPEN_SHAREDCACHE
flag.
By default, this is disabled.
sourcepub fn journal_mode(self, mode: SqliteJournalMode) -> SqliteConnectOptions
pub fn journal_mode(self, mode: SqliteJournalMode) -> SqliteConnectOptions
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.
sourcepub fn locking_mode(self, mode: SqliteLockingMode) -> SqliteConnectOptions
pub fn locking_mode(self, mode: SqliteLockingMode) -> SqliteConnectOptions
Sets the locking mode for the database connection.
The default locking mode is NORMAL.
sourcepub fn read_only(self, read_only: bool) -> SqliteConnectOptions
pub fn read_only(self, read_only: bool) -> SqliteConnectOptions
Sets the access mode to open the database for read-only access.
sourcepub fn create_if_missing(self, create: bool) -> SqliteConnectOptions
pub fn create_if_missing(self, create: bool) -> SqliteConnectOptions
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.
sourcepub fn statement_cache_capacity(self, capacity: usize) -> SqliteConnectOptions
pub fn statement_cache_capacity(self, capacity: usize) -> SqliteConnectOptions
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.
sourcepub fn busy_timeout(self, timeout: Duration) -> SqliteConnectOptions
pub fn busy_timeout(self, timeout: Duration) -> SqliteConnectOptions
Sets a timeout value to wait when the database is locked, before returning a busy timeout error.
The default busy timeout is 5 seconds.
sourcepub fn synchronous(self, synchronous: SqliteSynchronous) -> SqliteConnectOptions
pub fn synchronous(self, synchronous: SqliteSynchronous) -> SqliteConnectOptions
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.
sourcepub fn auto_vacuum(self, auto_vacuum: SqliteAutoVacuum) -> SqliteConnectOptions
pub fn auto_vacuum(self, auto_vacuum: SqliteAutoVacuum) -> SqliteConnectOptions
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.
sourcepub fn page_size(self, page_size: u32) -> SqliteConnectOptions
pub fn page_size(self, page_size: u32) -> SqliteConnectOptions
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.
sourcepub fn pragma<K, V>(self, key: K, value: V) -> SqliteConnectOptionswhere
K: Into<Cow<'static, str>>,
V: Into<Cow<'static, str>>,
pub fn pragma<K, V>(self, key: K, value: V) -> SqliteConnectOptionswhere K: Into<Cow<'static, str>>, V: Into<Cow<'static, str>>,
Sets custom initial pragma for the database connection.
sourcepub fn collation<N, F>(self, name: N, collate: F) -> SqliteConnectOptionswhere
N: Into<Arc<str>>,
F: Fn(&str, &str) -> Ordering + Send + Sync + 'static,
pub fn collation<N, F>(self, name: N, collate: F) -> SqliteConnectOptionswhere 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.
sourcepub fn immutable(self, immutable: bool) -> SqliteConnectOptions
pub fn immutable(self, immutable: bool) -> SqliteConnectOptions
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.
sourcepub fn serialized(self, serialized: bool) -> SqliteConnectOptions
pub fn serialized(self, serialized: bool) -> SqliteConnectOptions
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.
sourcepub fn thread_name(
self,
generator: impl Fn(u64) -> String + Send + Sync + 'static
) -> SqliteConnectOptions
pub fn thread_name( self, generator: impl Fn(u64) -> String + Send + Sync + 'static ) -> SqliteConnectOptions
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.
sourcepub fn command_buffer_size(self, size: usize) -> SqliteConnectOptions
pub fn command_buffer_size(self, size: usize) -> SqliteConnectOptions
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.
sourcepub fn row_buffer_size(self, size: usize) -> SqliteConnectOptions
pub fn row_buffer_size(self, size: usize) -> SqliteConnectOptions
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.
sourcepub fn vfs(self, vfs_name: impl Into<Cow<'static, str>>) -> SqliteConnectOptions
pub fn vfs(self, vfs_name: impl Into<Cow<'static, str>>) -> SqliteConnectOptions
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.
sourcepub fn extension(
self,
extension_name: impl Into<Cow<'static, str>>
) -> SqliteConnectOptions
pub fn extension( self, extension_name: impl Into<Cow<'static, str>> ) -> SqliteConnectOptions
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.
use std::str::FromStr;
use sqlx::sqlite::SqliteConnectOptions;
let options = SqliteConnectOptions::from_str("sqlite://data.db")?
.extension("vsv")
.extension("mod_spatialite");
sourcepub fn extension_with_entrypoint(
self,
extension_name: impl Into<Cow<'static, str>>,
entry_point: impl Into<Cow<'static, str>>
) -> SqliteConnectOptions
pub fn extension_with_entrypoint( self, extension_name: impl Into<Cow<'static, str>>, entry_point: impl Into<Cow<'static, str>> ) -> SqliteConnectOptions
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.
Trait Implementations§
source§impl Clone for SqliteConnectOptions
impl Clone for SqliteConnectOptions
source§fn clone(&self) -> SqliteConnectOptions
fn clone(&self) -> SqliteConnectOptions
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read moresource§impl ConnectOptions for SqliteConnectOptions
impl ConnectOptions for SqliteConnectOptions
type Connection = SqliteConnection
source§fn connect(
&self
) -> Pin<Box<dyn Future<Output = Result<<SqliteConnectOptions as ConnectOptions>::Connection, Error>> + Send, Global>>where
<SqliteConnectOptions as ConnectOptions>::Connection: Sized,
fn connect( &self ) -> Pin<Box<dyn Future<Output = Result<<SqliteConnectOptions as ConnectOptions>::Connection, Error>> + Send, Global>>where <SqliteConnectOptions as ConnectOptions>::Connection: Sized,
self
.source§fn log_statements(&mut self, level: LevelFilter) -> &mut SqliteConnectOptions
fn log_statements(&mut self, level: LevelFilter) -> &mut SqliteConnectOptions
level
source§fn log_slow_statements(
&mut self,
level: LevelFilter,
duration: Duration
) -> &mut SqliteConnectOptions
fn log_slow_statements( &mut self, level: LevelFilter, duration: Duration ) -> &mut SqliteConnectOptions
duration
at the specified level
.