Repository: diesel-rs/diesel
File: diesel/src/sqlite/connection/mod.rs (Rust)

Code before:
///
/// - Cause **linker errors** at compile time if the user's `libsqlite3-sys` wasn't compiled
///   with the required flags, or
/// - Cause **undefined behavior** at runtime if Diesel called functions that don't exist
///   in the linked library.
///
/// While feature gates could theoretically solve this problem, Diesel already has an
/// extensive API surface with many existing feature combinations. Each new feature gate
/// adds a **combinatorial explosion** of test configurations that must be validated,
/// making the library increasingly difficult to maintain. Therefore, exposing the raw
/// connection is the preferred approach for niche SQLite features.
///
/// By exposing the raw connection handle, Diesel allows users who **know** they have
/// access to a properly configured SQLite build to use these advanced features directly
/// through their own FFI bindings.
///
/// # Safety
///
/// The `with_raw_connection` method is marked `unsafe` because improper use
/// of the raw connection handle can lead to undefined behavior. The caller
/// must ensure that:
///
/// - The connection handle is **not closed** during the callback.
/// - The connection handle is **not stored** beyond the callback's scope.
/// - Any state changes made through the raw handle are **compatible** with
///   Diesel's expectations about the connection state.
/// - Concurrent access rules are respected (SQLite connections are not thread-safe
///   unless using serialized threading mode).
///
/// # Example
///
/// ```rust
/// use diesel::sqlite::{SqliteConnection, WithRawConnection};
/// use diesel::Connection;
///
/// let mut conn = SqliteConnection::establish(":memory:").unwrap();
///
/// // SAFETY: We do not close or store the connection handle,
/// // and we do not modify state that Diesel depends on.
/// let version = unsafe {
///     conn.with_raw_connection(|_raw_conn| {
///         // Use raw_conn with SQLite C API functions from your own
///         // `libsqlite3-sys` (native) or `sqlite-wasm-rs` (WASM) dependency.
///         // For example: ffi::sqlite3session_create(raw_conn, ...)
///         42 // return a value
///     })
/// };
/// assert_eq!(version, 42);
/// ```
///
/// # Platform Notes

Review comment (performance):
While this part is technically correct, it doesn't really say much about the expectations here. 

In the end we need to disallow anything that could mess up the internal prepared statement cache or transaction manager. So essentially no statements/function calls that invalidate the state of prepared statements in any way and no calls that might change the transaction state.

Code after:
    ///
    /// [`AnsiTransactionManager`]: crate::connection::AnsiTransactionManager
    ///
    /// # Example
    ///
    /// ```rust
    /// use diesel::sqlite::SqliteConnection;
    /// use diesel::Connection;
    ///
    /// let mut conn = SqliteConnection::establish(":memory:").unwrap();
    ///
    /// // SAFETY: We do not close or store the connection handle,
    /// // and we do not modify Diesel-managed state (transactions, cached statements).
    /// let is_valid = unsafe {
    ///     conn.with_raw_connection(|raw_conn| {
    ///         // The raw connection pointer can be passed to SQLite C API functions
    ///         // from your own `libsqlite3-sys` (native) or `sqlite-wasm-rs` (WASM)
    ///         // dependency — for example, `sqlite3_get_autocommit(raw_conn)` or
    ///         // `sqlite3session_create(raw_conn, ...)`.
    ///         !raw_conn.is_null()
    ///     })
    /// };
    /// assert!(is_valid);
    /// ```
    ///
    /// # Platform Notes
    ///
    /// This method works identically on both native and WASM targets. However,
    /// you must depend on the appropriate FFI crate for your target:
    ///
    /// - **Native**: Add `libsqlite3-sys` as a dependency
    /// - **WASM** (`wasm32-unknown-unknown`): Add `sqlite-wasm-rs` as a dependency
    ///
    /// Both crates expose a compatible `sqlite3` type that can be used with the
    /// pointer returned by this method.
    #[allow(unsafe_code)]
    pub unsafe fn with_raw_connection<R, F>(&mut self, f: F) -> R
    where
        F: FnOnce(*mut ffi::sqlite3) -> R,
    {
        f(self.raw_connection.internal_connection.as_ptr())
    }

    fn register_diesel_sql_functions(&self) -> QueryResult<()> {
        use crate::sql_types::{Integer, Text};

        functions::register::<Text, Integer, _, _, _>(
            &self.raw_connection,
            "diesel_manage_updated_at",
            false,
            |conn, table_name: String| {