sqlx_build_trust_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//! For portability, we enable the `bundled` feature which builds and links SQLite from source.
6//!
7//! We reserve the right to upgrade the version of `libsqlite3-sys` as necessary to pick up new
8//! `3.x.y` versions of SQLite.
9//!
10//! Due to Cargo's requirement that only one version of a crate that links a given native library
11//! exists in the dependency graph at a time, using SQLx alongside another crate linking
12//! `libsqlite3-sys` like `rusqlite` is a semver hazard.
13//!
14//! If you are doing so, we recommend pinning the version of both SQLx and the other crate you're
15//! using to prevent a `cargo update` from breaking things, e.g.:
16//!
17//! ```toml
18//! sqlx = { version = "=0.7.0", features = ["sqlite"] }
19//! rusqlite = "=0.28.0"
20//! ```
21//!
22//! and then upgrade these crates in lockstep when necessary.
23
24// SQLite is a C library. All interactions require FFI which is unsafe.
25// All unsafe blocks should have comments pointing to SQLite docs and ensuring that we maintain
26// invariants.
27#![allow(unsafe_code)]
28
29#[macro_use]
30extern crate sqlx_build_trust_core as sqlx_core;
31
32use std::sync::atomic::AtomicBool;
33
34pub use arguments::{SqliteArgumentValue, SqliteArguments};
35pub use column::SqliteColumn;
36pub use connection::{LockedSqliteHandle, SqliteConnection};
37pub use database::Sqlite;
38pub use error::SqliteError;
39pub use options::{
40    SqliteAutoVacuum, SqliteConnectOptions, SqliteJournalMode, SqliteLockingMode, SqliteSynchronous,
41};
42pub use query_result::SqliteQueryResult;
43pub use row::SqliteRow;
44pub use statement::SqliteStatement;
45pub use transaction::SqliteTransactionManager;
46pub use type_info::SqliteTypeInfo;
47pub use value::{SqliteValue, SqliteValueRef};
48
49use crate::connection::establish::EstablishParams;
50
51pub(crate) use sqlx_core::driver_prelude::*;
52
53use sqlx_core::describe::Describe;
54use sqlx_core::error::Error;
55use sqlx_core::executor::Executor;
56
57mod arguments;
58mod column;
59mod connection;
60mod database;
61mod error;
62mod logger;
63mod options;
64mod query_result;
65mod row;
66mod statement;
67mod transaction;
68mod type_info;
69pub mod types;
70mod value;
71
72#[cfg(feature = "any")]
73pub mod any;
74
75#[cfg(feature = "regexp")]
76mod regexp;
77
78#[cfg(feature = "migrate")]
79mod migrate;
80
81#[cfg(feature = "migrate")]
82mod testing;
83
84/// An alias for [`Pool`][crate::pool::Pool], specialized for SQLite.
85pub type SqlitePool = crate::pool::Pool<Sqlite>;
86
87/// An alias for [`PoolOptions`][crate::pool::PoolOptions], specialized for SQLite.
88pub type SqlitePoolOptions = crate::pool::PoolOptions<Sqlite>;
89
90/// An alias for [`Executor<'_, Database = Sqlite>`][Executor].
91pub trait SqliteExecutor<'c>: Executor<'c, Database = Sqlite> {}
92impl<'c, T: Executor<'c, Database = Sqlite>> SqliteExecutor<'c> for T {}
93
94// NOTE: required due to the lack of lazy normalization
95impl_into_arguments_for_arguments!(SqliteArguments<'q>);
96impl_column_index_for_row!(SqliteRow);
97impl_column_index_for_statement!(SqliteStatement);
98impl_acquire!(Sqlite, SqliteConnection);
99
100// required because some databases have a different handling of NULL
101impl_encode_for_option!(Sqlite);
102
103/// UNSTABLE: for use by `sqlx-cli` only.
104#[doc(hidden)]
105pub static CREATE_DB_WAL: AtomicBool = AtomicBool::new(true);
106
107/// UNSTABLE: for use by `sqlite-macros-core` only.
108#[doc(hidden)]
109pub fn describe_blocking(query: &str, database_url: &str) -> Result<Describe<Sqlite>, Error> {
110    let opts: SqliteConnectOptions = database_url.parse()?;
111    let params = EstablishParams::from_options(&opts)?;
112    let mut conn = params.establish()?;
113
114    // Execute any ancillary `PRAGMA`s
115    connection::execute::iter(&mut conn, &opts.pragma_string(), None, false)?.finish()?;
116
117    connection::describe::describe(&mut conn, query)
118
119    // SQLite database is closed immediately when `conn` is dropped
120}