SQLite: Deserialize database from in-memory buffer

CHANGELOG.md

@@ -24,6 +24,8 @@ Increasing the minimal supported Rust version will always be coupled at least wi
 
 ### Added
 
+* Added `serialize_database_to_buffer` and `deserialize_readonly_database_from_buffer` methods in `SqliteConnection` to support serialization/deserialization of SQLite databases to and from byte buffers.
+* Added `SerializedDatabase` wrapper type for a serialized database that is dynamically allocated by calling `serialize_database_to_buffer`. This RAII wrapper deallocates the memory when it goes out of scope with `sqlite3_free`.
 * Added the `custom_type_derives` config option to customize the derives for SQL
   type definitions automatically generated by Diesel CLI.
 * Add a `#[derive(MultiConnection)]` proc-macro that lets you easily implement `diesel::Connection`

diesel/src/sqlite/connection/mod.rs

@@ -4,12 +4,14 @@ mod bind_collector;
 mod functions;
 mod raw;
 mod row;
+mod serialized_database;
 mod sqlite_value;
 mod statement_iterator;
 mod stmt;
 
 pub(in crate::sqlite) use self::bind_collector::SqliteBindCollector;
 pub use self::bind_collector::SqliteBindValue;
+pub use self::serialized_database::SerializedDatabase;
 pub use self::sqlite_value::SqliteValue;
 
 use std::os::raw as libc;
@@ -406,6 +408,58 @@ impl SqliteConnection {
             .register_collation_function(collation_name, collation)
     }
 
+    /// Serialize the current SQLite database into a byte buffer.
+    ///
+    /// The serialized data is identical to the data that would be written to disk if the database
+    /// was saved in a file.
+    ///
+    /// # Returns
+    ///
+    /// This function returns a byte slice representing the serialized database.
+    pub fn serialize_database_to_buffer(&mut self) -> SerializedDatabase {
+        self.raw_connection.serialize()
+    }
+
+    /// Deserialize an SQLite database from a byte buffer.
+    ///
+    /// This function takes a byte slice and attempts to deserialize it into a SQLite database.
+    /// If successful, the database is loaded into the connection. If the deserialization fails,
+    /// an error is returned.
+    ///
+    /// The database is opened in READONLY mode.
+    ///
+    /// # Example
+    ///
+    /// ```no_run
+    /// # use diesel::sqlite::SerializedDatabase;
+    /// # use diesel::sqlite::SqliteConnection;
+    /// # use diesel::result::QueryResult;
+    /// # use diesel::sql_query;
+    /// # use diesel::Connection;
+    /// # use diesel::RunQueryDsl;
+    /// # fn main() {
+    /// let connection = &mut SqliteConnection::establish(":memory:").unwrap();
+    ///
+    /// sql_query("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)")
+    ///     .execute(connection).unwrap();
+    /// sql_query("INSERT INTO users (name, email) VALUES ('John Doe', '[email protected]'), ('Jane Doe', '[email protected]')")
+    ///     .execute(connection).unwrap();
+    ///
+    /// // Serialize the database to a byte vector
+    /// let serialized_db: SerializedDatabase = connection.serialize_database_to_buffer();
+    ///
+    /// // Create a new in-memory SQLite database
+    /// let connection = &mut SqliteConnection::establish(":memory:").unwrap();
+    ///
+    /// // Deserialize the byte vector into the new database
+    /// connection.deserialize_readonly_database_from_buffer(serialized_db.as_slice()).unwrap();
+    /// #
+    /// # }
+    /// ```
+    pub fn deserialize_readonly_database_from_buffer(&mut self, data: &[u8]) -> QueryResult<()> {
+        self.raw_connection.deserialize(data)
+    }
+
     fn register_diesel_sql_functions(&self) -> QueryResult<()> {
         use crate::sql_types::{Integer, Text};
 
@@ -436,6 +490,41 @@ mod tests {
     use crate::prelude::*;
     use crate::sql_types::Integer;
 
+    #[test]
+    fn database_serializes_and_deserializes_successfully() {
+        let expected_users = vec![
+            (
+                1,
+                "John Doe".to_string(),
+                "[email protected]".to_string(),
+            ),
+            (
+                2,
+                "Jane Doe".to_string(),
+                "[email protected]".to_string(),
+            ),
+        ];
+
+        let connection = &mut SqliteConnection::establish(":memory:").unwrap();
+        let _ =
+            crate::sql_query("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT)")
+                .execute(connection);
+        let _ = crate::sql_query("INSERT INTO users (name, email) VALUES ('John Doe', '[email protected]'), ('Jane Doe', '[email protected]')")
+            .execute(connection);
+
+        let serialized_database = connection.serialize_database_to_buffer();
+
+        let connection = &mut SqliteConnection::establish(":memory:").unwrap();
+        connection
+            .deserialize_readonly_database_from_buffer(serialized_database.as_slice())
+            .unwrap();
+
+        let query = sql::<(Integer, Text, Text)>("SELECT id, name, email FROM users ORDER BY id");
+        let actual_users = query.load::<(i32, String, String)>(connection).unwrap();
+
+        assert_eq!(expected_users, actual_users);
+    }
+
     #[test]
     fn prepared_statements_are_cached_when_run() {
         let connection = &mut SqliteConnection::establish(":memory:").unwrap();

diesel/src/sqlite/connection/raw.rs

@@ -8,6 +8,7 @@ use std::ptr::NonNull;
 use std::{mem, ptr, slice, str};
 
 use super::functions::{build_sql_function_args, process_sql_function_result};
+use super::serialized_database::SerializedDatabase;
 use super::stmt::ensure_sqlite_ok;
 use super::{Sqlite, SqliteAggregateFunction};
 use crate::deserialize::FromSqlRow;
@@ -185,6 +186,34 @@ impl RawConnection {
         result
     }
 
+    pub(super) fn serialize(&mut self) -> SerializedDatabase {
+        unsafe {
+            let mut size: ffi::sqlite3_int64 = 0;
+            let data_ptr = ffi::sqlite3_serialize(
+                self.internal_connection.as_ptr(),
+                std::ptr::null(),
+                &mut size as *mut _,
+                0,
+            );
+            SerializedDatabase::new(data_ptr, size as usize)
+        }
+    }
+
+    pub(super) fn deserialize(&mut self, data: &[u8]) -> QueryResult<()> {
+        unsafe {
+            let result = ffi::sqlite3_deserialize(
+                self.internal_connection.as_ptr(),
+                std::ptr::null(),
+                data.as_ptr() as *mut u8,
+                data.len() as i64,
+                data.len() as i64,
+                ffi::SQLITE_DESERIALIZE_READONLY as u32,
+            );
+
+            ensure_sqlite_ok(result, self.internal_connection.as_ptr())
+        }
+    }
+
     fn get_fn_name(fn_name: &str) -> Result<CString, NulError> {
         CString::new(fn_name)
     }

diesel/src/sqlite/connection/serialized_database.rs

@@ -0,0 +1,42 @@
+#![allow(unsafe_code)]
+extern crate libsqlite3_sys as ffi;
+
+use std::ops::Deref;
+
+/// `SerializedDatabase` is a wrapper for a serialized database that is dynamically allocated by calling `sqlite3_serialize`.
+/// This RAII wrapper is necessary to deallocate the memory when it goes out of scope with `sqlite3_free`.
+#[derive(Debug)]
+pub struct SerializedDatabase {
+    data: *mut u8,
+    len: usize,
+}
+
+impl SerializedDatabase {
+    /// Creates a new `SerializedDatabase` with the given data pointer and length.
+    pub fn new(data: *mut u8, len: usize) -> Self {
+        Self { data, len }
+    }
+
+    /// Returns a slice of the serialized database.
+    pub fn as_slice(&self) -> &[u8] {
+        // The pointer is never null because we don't pass the NO_COPY flag
+        unsafe { std::slice::from_raw_parts(self.data, self.len) }
+    }
+}
+
+impl Deref for SerializedDatabase {
+    type Target = [u8];
+
+    fn deref(&self) -> &Self::Target {
+        self.as_slice()
+    }
+}
+
+impl Drop for SerializedDatabase {
+    /// Deallocates the memory of the serialized database when it goes out of scope.
+    fn drop(&mut self) {
+        unsafe {
+            ffi::sqlite3_free(self.data as _);
+        }
+    }
+}

diesel/src/sqlite/mod.rs

@@ -13,6 +13,7 @@ pub mod query_builder;
 mod types;
 
 pub use self::backend::{Sqlite, SqliteType};
+pub use self::connection::SerializedDatabase;
 pub use self::connection::SqliteBindValue;
 pub use self::connection::SqliteConnection;
 pub use self::connection::SqliteValue;