bindgen_bundled_version.rs

Overview

This Rust source file provides raw FFI (Foreign Function Interface) bindings to the SQLite3 C API. It is automatically generated by rust-bindgen to allow Rust code to call SQLite3 functions, use its types, and access constants directly. The file exposes low-level SQLite3 functionality including database connection management, SQL statement preparation and execution, virtual file system (VFS) interfaces, virtual tables, memory management, concurrency control via mutexes, full-text search (FTS5) APIs, and change set/session management.

The file primarily consists of:

This file serves as the foundational low-level SQLite3 API interface for higher-level Rust wrappers and modules, enabling direct interoperability with the SQLite3 engine.

Key Constants

The file defines numerous SQLite3 constants representing:

These constants are used throughout the SQLite3 API to control behavior and report statuses.

Primary Structs and Types

sqlite3

#[repr(C)]
#[derive(Debug, Copy, Clone)]
pub struct sqlite3 {
    _unused: [u8; 0],
}

Represents an opaque SQLite3 database connection handle. It is used in most database-related function calls.

sqlite3_stmt

#[repr(C)]
#[derive(Debug, Copy, Clone)]
pub struct sqlite3_stmt {
    _unused: [u8; 0],
}

Represents a prepared SQL statement object. Used for compiling and executing SQL queries.

sqlite3_file and sqlite3_io_methods

These structs define the interface for SQLite3's virtual file system abstraction.

This abstraction allows SQLite3 to be ported to different platforms by implementing these methods.

sqlite3_mutex and sqlite3_mutex_methods

Represents mutex objects used internally by SQLite3 to provide thread safety and concurrency control.

sqlite3_vfs

Defines the interface for SQLite3's Virtual File System layer, including methods for file operations, randomness, time, system calls, and dynamic loading.

sqlite3_value and sqlite3_context

Opaque types representing SQL values and user-defined function contexts respectively, used in creating and handling custom SQL functions.

fts5_api, Fts5Context, and related structs

These structs provide the API and context for SQLite3's Full-Text Search (FTS5) extension. They allow tokenizing, querying, and managing FTS5 virtual tables and extension functions.

Important Functions and Their Usage

sqlite3_auto_extension and sqlite3_cancel_auto_extension

pub fn sqlite3_auto_extension(
    xEntryPoint: Option<unsafe extern "C" fn(db: *mut sqlite3, pzErrMsg: *mut *mut c_char, _: *const sqlite3_api_routines) -> c_int>,
) -> c_int;
pub fn sqlite3_cancel_auto_extension(
    xEntryPoint: Option<unsafe extern "C" fn(db: *mut sqlite3, pzErrMsg: *mut *mut c_char, _: *const sqlite3_api_routines) -> c_int>,
) -> c_int;

sqlite3_open and sqlite3_open_v2

pub fn sqlite3_open(filename: *const c_char, ppDb: *mut *mut sqlite3) -> c_int;
pub fn sqlite3_open_v2(filename: *const c_char, ppDb: *mut *mut sqlite3, flags: c_int, zVfs: *const c_char) -> c_int;

sqlite3_prepare_v2 and sqlite3_prepare_v3

pub fn sqlite3_prepare_v2(
    db: *mut sqlite3,
    zSql: *const c_char,
    nByte: c_int,
    ppStmt: *mut *mut sqlite3_stmt,
    pzTail: *mut *const c_char,
) -> c_int;

pub fn sqlite3_prepare_v3(
    db: *mut sqlite3,
    zSql: *const c_char,
    nByte: c_int,
    prepFlags: c_uint,
    ppStmt: *mut *mut sqlite3_stmt,
    pzTail: *mut *const c_char,
) -> c_int;

sqlite3_step

pub fn sqlite3_step(pStmt: *mut sqlite3_stmt) -> c_int;

sqlite3_finalize

pub fn sqlite3_finalize(pStmt: *mut sqlite3_stmt) -> c_int;

sqlite3_bind_* functions

Functions like sqlite3_bind_int, sqlite3_bind_text, sqlite3_bind_blob, etc., bind Rust data to SQL statement parameters by index.

Example:

pub fn sqlite3_bind_int(stmt: *mut sqlite3_stmt, index: c_int, value: c_int) -> c_int;

sqlite3_column_* functions

Functions like sqlite3_column_int, sqlite3_column_text, etc., retrieve column values from the current row of a result set.

Example:

pub fn sqlite3_column_text(stmt: *mut sqlite3_stmt, col: c_int) -> *const c_uchar;

sqlite3_exec

pub fn sqlite3_exec(
    db: *mut sqlite3,
    sql: *const c_char,
    callback: Option<unsafe extern "C" fn(*mut c_void, c_int, *mut *mut c_char, *mut *mut c_char) -> c_int>,
    arg: *mut c_void,
    errmsg: *mut *mut c_char,
) -> c_int;

sqlite3_create_function_v2

Allows creation of custom SQL scalar or aggregate functions.

pub fn sqlite3_create_function_v2(
    db: *mut sqlite3,
    zFunctionName: *const c_char,
    nArg: c_int,
    eTextRep: c_int,
    pApp: *mut c_void,
    xFunc: Option<unsafe extern "C" fn(*mut sqlite3_context, c_int, *mut *mut sqlite3_value)>,
    xStep: Option<unsafe extern "C" fn(*mut sqlite3_context, c_int, *mut *mut sqlite3_value)>,
    xFinal: Option<unsafe extern "C" fn(*mut sqlite3_context)>,
    xDestroy: Option<unsafe extern "C" fn(*mut c_void)>,
) -> c_int;

sqlite3_vfs and VFS Interface Functions

The sqlite3_vfs struct and related functions (sqlite3_vfs_find, sqlite3_vfs_register, sqlite3_vfs_unregister) allow SQLite3 to interact with different underlying file systems or OS abstractions.

sqlite3_backup API

Functions like sqlite3_backup_init, sqlite3_backup_step, and sqlite3_backup_finish provide API to copy data between databases incrementally.

sqlite3_mutex API

Mutex allocation, deallocation, and locking functions manage concurrency control in SQLite.

Full-Text Search (FTS5) Extension API

Change Set and Session APIs

Interactions with Other System Parts

This file exposes the core SQLite3 API for use by higher-level Rust modules managing database operations, custom extensions, virtual tables, full-text search features, and synchronization mechanisms. It interoperates primarily with:

Important Implementation Details

Selected Usage Examples

Opening a Database and Executing a Simple Query

use std::ffi::CString;

unsafe {
    let db_filename = CString::new("test.db").unwrap();
    let mut db: *mut sqlite3 = std::ptr::null_mut();

    let rc = sqlite3_open(db_filename.as_ptr(), &mut db);
    if rc != SQLITE_OK {
        // Handle open error
    }

    let sql = CString::new("CREATE TABLE IF NOT EXISTS users(id INTEGER PRIMARY KEY, name TEXT);").unwrap();
    let rc = sqlite3_exec(db, sql.as_ptr(), None, std::ptr::null_mut(), std::ptr::null_mut());
    if rc != SQLITE_OK {
        // Handle exec error
    }

    sqlite3_close(db);
}

Preparing and Executing a Parameterized Statement

use std::ffi::CString;

unsafe {
    let sql = CString::new("INSERT INTO users(name) VALUES(?1);").unwrap();
    let mut stmt: *mut sqlite3_stmt = std::ptr::null_mut();

    let rc = sqlite3_prepare_v2(db, sql.as_ptr(), -1, &mut stmt, std::ptr::null_mut());
    if rc == SQLITE_OK {
        let name = CString::new("Alice").unwrap();
        sqlite3_bind_text(stmt, 1, name.as_ptr(), -1, None);

        sqlite3_step(stmt);
        sqlite3_finalize(stmt);
    }
}

Mermaid Flowchart Diagram of Main Functions

flowchart TD
A[sqlite3_open / sqlite3_open_v2] --> B[sqlite3_prepare_v2 / sqlite3_prepare_v3]
B --> C[sqlite3_bind_* functions]
C --> D[sqlite3_step]
D -->|SQLITE_ROW| E[Retrieve data with sqlite3_column_*]
D -->|SQLITE_DONE| F[sqlite3_finalize]
A --> G[sqlite3_exec]
A --> H[sqlite3_close]
I[sqlite3_auto_extension] --> A
J[sqlite3_create_function_v2] --> B
K[sqlite3_vfs_register / sqlite3_vfs_unregister] --> A

This diagram depicts the typical flow for opening a database, preparing and executing SQL statements, binding parameters, retrieving results, and finalizing resources. It also shows registration of auto-extensions, custom functions, and virtual file systems.

Reference to Related Topics

For detailed usage and explanation of SQLite3 APIs, error codes, virtual tables, mutexes, and full-text search, see: