rust_rocksdb/
checkpoint.rs

1// Copyright 2018 Eugene P.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14//
15
16//! Implementation of bindings to RocksDB Checkpoint[1] API
17//!
18//! [1]: https://github.com/facebook/rocksdb/wiki/Checkpoints
19
20use crate::db::{DBInner, ExportImportFilesMetaData};
21use crate::{ffi, ffi_util::to_cpath, AsColumnFamilyRef, DBCommon, Error, ThreadMode};
22use std::{marker::PhantomData, path::Path};
23
24/// Undocumented parameter for `ffi::rocksdb_checkpoint_create` function. Zero by default.
25const LOG_SIZE_FOR_FLUSH: u64 = 0_u64;
26
27/// Database's checkpoint object.
28/// Used to create checkpoints of the specified DB from time to time.
29pub struct Checkpoint<'db> {
30    inner: *mut ffi::rocksdb_checkpoint_t,
31    _db: PhantomData<&'db ()>,
32}
33
34impl<'db> Checkpoint<'db> {
35    /// Creates new checkpoint object for specific DB.
36    ///
37    /// Does not actually produce checkpoints, call `.create_checkpoint()` method to produce
38    /// a DB checkpoint.
39    pub fn new<T: ThreadMode, I: DBInner>(db: &'db DBCommon<T, I>) -> Result<Self, Error> {
40        let checkpoint: *mut ffi::rocksdb_checkpoint_t;
41
42        unsafe {
43            checkpoint = ffi_try!(ffi::rocksdb_checkpoint_object_create(db.inner.inner()));
44        }
45
46        if checkpoint.is_null() {
47            return Err(Error::new("Could not create checkpoint object.".to_owned()));
48        }
49
50        Ok(Self {
51            inner: checkpoint,
52            _db: PhantomData,
53        })
54    }
55
56    /// Creates new physical DB checkpoint in directory specified by `path`.
57    pub fn create_checkpoint<P: AsRef<Path>>(&self, path: P) -> Result<(), Error> {
58        let c_path = to_cpath(path)?;
59        unsafe {
60            ffi_try!(ffi::rocksdb_checkpoint_create(
61                self.inner,
62                c_path.as_ptr(),
63                LOG_SIZE_FOR_FLUSH,
64            ));
65        }
66        Ok(())
67    }
68
69    /// Export a specified Column Family
70    ///
71    /// Creates copies of the live SST files at the specified export path.
72    ///
73    /// - SST files will be created as hard links when the directory specified
74    ///   is in the same partition as the db directory, copied otherwise.
75    /// - the path must not yet exist - a new directory will be created as part of the export.
76    /// - Always triggers a flush.
77    ///
78    /// # Examples
79    ///
80    /// ```rust
81    /// use rust_rocksdb::{DB, checkpoint::Checkpoint};
82    ///
83    /// fn export_column_family(db: &DB, column_family_name: &str, export_path: &str) {
84    ///    let cp = Checkpoint::new(&db).unwrap();
85    ///    let cf = db.cf_handle(column_family_name).unwrap();
86    ///
87    ///    let export_metadata = cp.export_column_family(&cf, export_path).unwrap();
88    ///
89    ///    assert!(export_metadata.get_files().len() > 0);
90    /// }
91    /// ```
92    ///
93    /// See also: [`DB::create_column_family_with_import`](crate::DB::create_column_family_with_import).
94    pub fn export_column_family<P: AsRef<Path>>(
95        &self,
96        column_family: &impl AsColumnFamilyRef,
97        path: P,
98    ) -> Result<ExportImportFilesMetaData, Error> {
99        let c_path = to_cpath(path)?;
100        let column_family_handle = column_family.inner();
101        let metadata = unsafe {
102            ffi_try!(ffi::rocksdb_checkpoint_export_column_family(
103                self.inner,
104                column_family_handle,
105                c_path.as_ptr(),
106            ))
107        };
108        Ok(ExportImportFilesMetaData { inner: metadata })
109    }
110}
111
112impl Drop for Checkpoint<'_> {
113    fn drop(&mut self) {
114        unsafe {
115            ffi::rocksdb_checkpoint_object_destroy(self.inner);
116        }
117    }
118}
rust_rocksdb/checkpoint.rs

rust_rocksdb/
checkpoint.rs
