sqlx_sqlite/
lib.rs

1//! **SQLite** database driver.
2//!
3//! ### Note: linkage is semver-exempt.
4//! This driver uses the `libsqlite3-sys` crate which links the native library for SQLite 3.
5//! With the "sqlite" feature, we enable the `bundled` feature which builds and links SQLite from
6//! source.
7//!
8//! We reserve the right to upgrade the version of `libsqlite3-sys` as necessary to pick up new
9//! `3.x.y` versions of SQLite.
10//!
11//! Due to Cargo's requirement that only one version of a crate that links a given native library
12//! exists in the dependency graph at a time, using SQLx alongside another crate linking
13//! `libsqlite3-sys` like `rusqlite` is a semver hazard.
14//!
15//! If you are doing so, we recommend pinning the version of both SQLx and the other crate you're
16//! using to prevent a `cargo update` from breaking things, e.g.:
17//!
18//! ```toml
19//! sqlx = { version = "=0.8.1", features = ["sqlite"] }
20//! rusqlite = "=0.32.1"
21//! ```
22//!
23//! and then upgrade these crates in lockstep when necessary.
24//!
25//! ### Dynamic linking
26//! To dynamically link to a system SQLite library, the "sqlite-unbundled" feature can be used
27//! instead.
28//!
29//! This allows updating SQLite independently of SQLx or using forked versions, but you must have
30//! SQLite installed on the system or provide a path to the library at build time (See
31//! [the `rusqlite` README](https://github.com/rusqlite/rusqlite?tab=readme-ov-file#notes-on-building-rusqlite-and-libsqlite3-sys)
32//! for details).
33//!
34//! It may result in link errors if the SQLite version is too old. Version `3.20.0` or newer is
35//! recommended. It can increase build time due to the use of bindgen.
36
37// SQLite is a C library. All interactions require FFI which is unsafe.
38// All unsafe blocks should have comments pointing to SQLite docs and ensuring that we maintain
39// invariants.
40#![allow(unsafe_code)]
41
42#[macro_use]
43extern crate sqlx_core;
44
45use std::sync::atomic::AtomicBool;
46
47pub use arguments::{SqliteArgumentValue, SqliteArguments};
48pub use column::SqliteColumn;
49pub use connection::serialize::SqliteOwnedBuf;
50#[cfg(feature = "preupdate-hook")]
51pub use connection::PreupdateHookResult;
52pub use connection::{LockedSqliteHandle, SqliteConnection, SqliteOperation, UpdateHookResult};
53pub use database::Sqlite;
54pub use error::SqliteError;
55pub use options::{
56    SqliteAutoVacuum, SqliteConnectOptions, SqliteJournalMode, SqliteLockingMode, SqliteSynchronous,
57};
58pub use query_result::SqliteQueryResult;
59pub use row::SqliteRow;
60pub use statement::SqliteStatement;
61pub use transaction::SqliteTransactionManager;
62pub use type_info::SqliteTypeInfo;
63pub use value::{SqliteValue, SqliteValueRef};
64
65use crate::connection::establish::EstablishParams;
66
67pub(crate) use sqlx_core::driver_prelude::*;
68
69use sqlx_core::describe::Describe;
70use sqlx_core::error::Error;
71use sqlx_core::executor::Executor;
72
73mod arguments;
74mod column;
75mod connection;
76mod database;
77mod error;
78mod logger;
79mod options;
80mod query_result;
81mod row;
82mod statement;
83mod transaction;
84mod type_checking;
85mod type_info;
86pub mod types;
87mod value;
88
89#[cfg(feature = "any")]
90pub mod any;
91
92#[cfg(feature = "regexp")]
93mod regexp;
94
95#[cfg(feature = "migrate")]
96mod migrate;
97
98#[cfg(feature = "migrate")]
99mod testing;
100
101/// An alias for [`Pool`][crate::pool::Pool], specialized for SQLite.
102pub type SqlitePool = crate::pool::Pool<Sqlite>;
103
104/// An alias for [`PoolOptions`][crate::pool::PoolOptions], specialized for SQLite.
105pub type SqlitePoolOptions = crate::pool::PoolOptions<Sqlite>;
106
107/// An alias for [`Executor<'_, Database = Sqlite>`][Executor].
108pub trait SqliteExecutor<'c>: Executor<'c, Database = Sqlite> {}
109impl<'c, T: Executor<'c, Database = Sqlite>> SqliteExecutor<'c> for T {}
110
111/// An alias for [`Transaction`][sqlx_core::transaction::Transaction], specialized for SQLite.
112pub type SqliteTransaction<'c> = sqlx_core::transaction::Transaction<'c, Sqlite>;
113
114// NOTE: required due to the lack of lazy normalization
115impl_into_arguments_for_arguments!(SqliteArguments<'q>);
116impl_column_index_for_row!(SqliteRow);
117impl_column_index_for_statement!(SqliteStatement);
118impl_acquire!(Sqlite, SqliteConnection);
119
120// required because some databases have a different handling of NULL
121impl_encode_for_option!(Sqlite);
122
123/// UNSTABLE: for use by `sqlx-cli` only.
124#[doc(hidden)]
125pub static CREATE_DB_WAL: AtomicBool = AtomicBool::new(true);
126
127/// UNSTABLE: for use by `sqlite-macros-core` only.
128#[doc(hidden)]
129pub fn describe_blocking(query: &str, database_url: &str) -> Result<Describe<Sqlite>, Error> {
130    let opts: SqliteConnectOptions = database_url.parse()?;
131    let params = EstablishParams::from_options(&opts)?;
132    let mut conn = params.establish()?;
133
134    // Execute any ancillary `PRAGMA`s
135    connection::execute::iter(&mut conn, &opts.pragma_string(), None, false)?.finish()?;
136
137    connection::describe::describe(&mut conn, query)
138
139    // SQLite database is closed immediately when `conn` is dropped
140}
sqlx_sqlite/lib.rs

sqlx_sqlite/
lib.rs
