Skip to main content

rusqlite/
serialize.rs

1//! Serialize a database.
2use std::marker::PhantomData;
3use std::ops::{Deref, DerefMut};
4use std::ptr::NonNull;
5
6use crate::error::{error_from_handle, error_from_sqlite_code};
7use crate::ffi;
8use crate::{Connection, Error, Name, Result};
9
10/// Shared (`SQLITE_SERIALIZE_NOCOPY`) serialized database
11pub struct SharedData<'conn> {
12    phantom: PhantomData<&'conn mut Connection>,
13    ptr: NonNull<u8>,
14    sz: usize,
15}
16
17/// Owned serialized database
18pub struct OwnedData {
19    ptr: NonNull<u8>,
20    sz: usize,
21}
22
23impl OwnedData {
24    /// # Safety
25    ///
26    /// Caller must be certain that `ptr` is allocated by `sqlite3_malloc64`.
27    #[must_use]
28    pub unsafe fn from_raw_nonnull(ptr: NonNull<u8>, sz: usize) -> Self {
29        Self { ptr, sz }
30    }
31
32    fn into_raw(self) -> (*mut u8, usize) {
33        let raw = (self.ptr.as_ptr(), self.sz);
34        std::mem::forget(self);
35        raw
36    }
37}
38
39impl Drop for OwnedData {
40    fn drop(&mut self) {
41        unsafe {
42            ffi::sqlite3_free(self.ptr.as_ptr().cast());
43        }
44    }
45}
46
47/// Serialized database
48pub enum Data<'conn> {
49    /// Shared (`SQLITE_SERIALIZE_NOCOPY`) serialized database
50    Shared(SharedData<'conn>),
51    /// Owned serialized database
52    Owned(OwnedData),
53}
54
55impl Deref for Data<'_> {
56    type Target = [u8];
57
58    fn deref(&self) -> &[u8] {
59        match self {
60            Data::Owned(od) => od.deref(),
61            Data::Shared(sd) => sd.deref(),
62        }
63    }
64}
65
66impl Deref for SharedData<'_> {
67    type Target = [u8];
68
69    fn deref(&self) -> &[u8] {
70        unsafe { std::slice::from_raw_parts(self.ptr.as_ptr(), self.sz) }
71    }
72}
73impl Deref for OwnedData {
74    type Target = [u8];
75
76    fn deref(&self) -> &[u8] {
77        unsafe { std::slice::from_raw_parts(self.ptr.as_ptr(), self.sz) }
78    }
79}
80impl DerefMut for OwnedData {
81    fn deref_mut(&mut self) -> &mut [u8] {
82        unsafe { std::slice::from_raw_parts_mut(self.ptr.as_mut(), self.sz) }
83    }
84}
85
86impl Connection {
87    /// Serialize a database.
88    ///
89    /// ```compile_fail
90    /// use rusqlite::{Connection, Result, MAIN_DB};
91    /// use rusqlite::serialize::Data;
92    /// fn main() -> Result<()> {
93    ///     let mut src = Connection::open_in_memory()?;
94    ///     let data = src.serialize(MAIN_DB)?;
95    ///     let mut dst = Connection::open_in_memory()?;
96    ///     let Data::Owned(data) = data else {
97    ///         panic!("expected OwnedData")
98    ///     };
99    ///     dst.deserialize(MAIN_DB, data, false)?;
100    ///     let data = dst.serialize(MAIN_DB).unwrap(); // mutable borrow occurs here
101    ///     dst.execute("INSERT INTO t VALUES (zeroblob(4096))", [])?; // <- immutable borrow occurs here
102    ///     let Data::Shared(_) = data else { // mutable borrow later used here
103    ///         panic!("expected SharedData")
104    ///     };
105    ///     Ok(())
106    /// }
107    /// ```
108    pub fn serialize<N: Name>(&mut self, schema: N) -> Result<Data<'_>> {
109        let schema = schema.as_cstr()?;
110        let mut sz = 0;
111        let mut ptr: *mut u8 = unsafe {
112            ffi::sqlite3_serialize(
113                self.handle(),
114                schema.as_ptr(),
115                &raw mut sz,
116                ffi::SQLITE_SERIALIZE_NOCOPY,
117            )
118        };
119        Ok(if ptr.is_null() {
120            ptr = unsafe { ffi::sqlite3_serialize(self.handle(), schema.as_ptr(), &raw mut sz, 0) };
121            if ptr.is_null() {
122                return Err(unsafe { error_from_handle(self.handle(), ffi::SQLITE_NOMEM) });
123            }
124            Data::Owned(OwnedData {
125                ptr: NonNull::new(ptr).unwrap(),
126                sz: sz.try_into().unwrap(),
127            })
128        } else {
129            // shared buffer
130            Data::Shared(SharedData {
131                ptr: NonNull::new(ptr).unwrap(),
132                sz: sz.try_into().unwrap(),
133                phantom: PhantomData,
134            })
135        })
136    }
137
138    /// Deserialize from stream
139    pub fn deserialize_read_exact<N: Name, R: std::io::Read>(
140        &mut self,
141        schema: N,
142        mut read: R,
143        sz: usize,
144        read_only: bool,
145    ) -> Result<()> {
146        let ptr = unsafe { ffi::sqlite3_malloc64(sz.try_into().unwrap()) }.cast::<u8>();
147        if ptr.is_null() {
148            return Err(error_from_sqlite_code(ffi::SQLITE_NOMEM, None));
149        }
150        let ptr = NonNull::new(ptr).unwrap();
151        let mut data = unsafe { OwnedData::from_raw_nonnull(ptr, sz) };
152        read.read_exact(data.deref_mut()).map_err(|e| {
153            Error::SqliteFailure(
154                ffi::Error {
155                    code: ffi::ErrorCode::CannotOpen,
156                    extended_code: ffi::SQLITE_IOERR,
157                },
158                Some(format!("{e}")),
159            )
160        })?;
161        self.deserialize(schema, data, read_only)
162    }
163
164    /// Deserialize `include_bytes` as a read only database
165    pub fn deserialize_bytes<N: Name>(&mut self, schema: N, data: &'static [u8]) -> Result<()> {
166        let sz = data.len().try_into().unwrap();
167        self.deserialize_(
168            schema,
169            data.as_ptr().cast_mut(),
170            sz,
171            ffi::SQLITE_DESERIALIZE_READONLY,
172        )
173    }
174
175    /// Deserialize a database.
176    pub fn deserialize<N: Name>(
177        &mut self,
178        schema: N,
179        data: OwnedData,
180        read_only: bool,
181    ) -> Result<()> {
182        let (data, sz) = data.into_raw();
183        let sz = sz.try_into().unwrap();
184        let flags = if read_only {
185            ffi::SQLITE_DESERIALIZE_FREEONCLOSE | ffi::SQLITE_DESERIALIZE_READONLY
186        } else {
187            ffi::SQLITE_DESERIALIZE_FREEONCLOSE | ffi::SQLITE_DESERIALIZE_RESIZEABLE
188        };
189        self.deserialize_(schema, data, sz, flags)
190        /* TODO
191        if let Some(mxSize) = mxSize {
192            unsafe {
193                ffi::sqlite3_file_control(
194                    self.handle(),
195                    schema.as_ptr(),
196                    ffi::SQLITE_FCNTL_SIZE_LIMIT,
197                    &mut mxSize,
198                )
199            };
200        }*/
201    }
202
203    fn deserialize_<N: Name>(
204        &mut self,
205        schema: N,
206        data: *mut u8,
207        sz: ffi::sqlite_int64,
208        flags: std::ffi::c_uint,
209    ) -> Result<()> {
210        let schema = schema.as_cstr()?;
211        let rc = unsafe {
212            ffi::sqlite3_deserialize(self.handle(), schema.as_ptr(), data, sz, sz, flags)
213        };
214        if rc != ffi::SQLITE_OK {
215            return Err(unsafe { error_from_handle(self.handle(), rc) });
216        }
217        Ok(())
218    }
219}
220
221#[cfg(all(test, not(miri)))]
222mod test {
223    use std::assert_matches;
224
225    #[cfg(all(target_family = "wasm", target_os = "unknown"))]
226    use wasm_bindgen_test::wasm_bindgen_test as test;
227
228    use super::*;
229    use crate::MAIN_DB;
230
231    #[test]
232    fn deserialize_short_read() -> Result<()> {
233        let mut dst = Connection::open_in_memory()?;
234        let read = b"";
235        assert_matches!(
236            dst.deserialize_read_exact(MAIN_DB, &read[..], 1024, true)
237                .unwrap_err(),
238            Error::SqliteFailure(
239                ffi::Error {
240                    code: ffi::ErrorCode::CannotOpen,
241                    extended_code: ffi::SQLITE_IOERR,
242                },
243                Some(_),
244            )
245        );
246        Ok(())
247    }
248}