sqlmodel-sqlite 0.2.2

SQLite driver for SQLModel Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113

//! SQLite driver for SQLModel Rust.
//!
//! `sqlmodel-sqlite` is the **SQLite driver** for the SQLModel ecosystem. It implements
//! the `Connection` trait from `sqlmodel-core`, providing a lightweight backend that is
//! ideal for local development, embedded use, and testing.
//!
//! # Role In The Architecture
//!
//! - Implements `sqlmodel-core::Connection` for SQLite
//! - Supplies FFI-backed execution and type conversion
//! - Enables `sqlmodel-query` and `sqlmodel-session` to run against SQLite
//!
// FFI bindings require unsafe code - this is expected for database drivers
#![allow(unsafe_code)]
//!
//! This crate provides a SQLite database driver using FFI bindings to libsqlite3.
//! It implements the `Connection` trait from sqlmodel-core for seamless integration
//! with the rest of the SQLModel ecosystem.
//!
//! # Features
//!
//! - Full Connection trait implementation
//! - Transaction support with savepoints
//! - Type-safe parameter binding
//! - In-memory and file-based databases
//! - Configurable open flags and busy timeout
//!
//! # Example
//!
//! ```rust,ignore
//! use sqlmodel_sqlite::{SqliteConnection, SqliteConfig};
//! use sqlmodel_core::{Connection, Value, Cx, Outcome};
//!
//! // Open an in-memory database
//! let conn = SqliteConnection::open_memory().unwrap();
//!
//! // Create a table
//! conn.execute_raw("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)").unwrap();
//!
//! // Insert data using the Connection trait
//! let cx = Cx::for_testing();
//! match conn.insert(&cx, "INSERT INTO users (name) VALUES (?)", &[Value::Text("Alice".into())]).await {
//!     Outcome::Ok(id) => println!("Inserted user with id: {}", id),
//!     Outcome::Err(e) => eprintln!("Error: {}", e),
//!     _ => {}
//! }
//! ```
//!
//! # Type Mapping
//!
//! | Rust Type | SQLite Type |
//! |-----------|-------------|
//! | `bool` | INTEGER (0/1) |
//! | `i8`, `i16`, `i32` | INTEGER |
//! | `i64` | INTEGER |
//! | `f32`, `f64` | REAL |
//! | `String` | TEXT |
//! | `Vec<u8>` | BLOB |
//! | `Option<T>` | NULL or T |
//! | `Date`, `Time`, `Timestamp` | TEXT (ISO-8601) |
//! | `Uuid` | BLOB (16 bytes) |
//! | `Json` | TEXT |
//!
//! # Thread Safety
//!
//! `SqliteConnection` is both `Send` and `Sync`, using internal mutex
//! synchronization to protect the underlying SQLite handle. This allows
//! connections to be shared across async tasks safely.

pub mod connection;
pub mod ffi;
pub mod types;

pub use connection::{OpenFlags, SqliteConfig, SqliteConnection, SqliteTransaction};

// Console integration (feature-gated)
#[cfg(feature = "console")]
pub use sqlmodel_console::ConsoleAware;

/// Re-export the SQLite library version.
pub fn sqlite_version() -> &'static str {
    ffi::version()
}

/// Re-export the SQLite library version number.
pub fn sqlite_version_number() -> i32 {
    ffi::version_number()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_sqlite_version() {
        let version = sqlite_version();
        assert!(
            version.starts_with('3'),
            "Expected SQLite 3.x, got {}",
            version
        );
    }

    #[test]
    fn test_sqlite_version_number() {
        let num = sqlite_version_number();
        assert!(
            num >= 3_000_000,
            "Expected SQLite 3.x.x (>= 3000000), got {}",
            num
        );
    }
}