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::{AsColumnFamilyRef, DBCommon, Error, ThreadMode, ffi, ffi_util::to_cpath};
22use std::{marker::PhantomData, path::Path};
23
24/// Default value for the `log_size_for_flush` parameter passed to
25/// `ffi::rocksdb_checkpoint_create`.
26///
27/// A value of `0` forces RocksDB to flush memtables as needed before creating
28/// the checkpoint. This helps ensure the checkpoint includes the most recent
29/// writes (which may still be in memtables at the time of checkpoint creation).
30///
31/// Forcing a flush can create new SST file(s), potentially very small L0 SSTs
32/// if little data has been written since the last flush.
33const DEFAULT_LOG_SIZE_FOR_FLUSH: u64 = 0_u64;
34
35/// Database's checkpoint object.
36/// Used to create checkpoints of the specified DB from time to time.
37///
38/// A `Checkpoint` must not outlive the `DB` it was created from:
39///
40/// ```compile_fail,E0597
41/// use rust_rocksdb::{checkpoint::Checkpoint, DB};
42///
43/// let _checkpoint = {
44/// let db = DB::open_default("foo").unwrap();
45/// Checkpoint::new(&db)
46/// };
47/// ```
48pub struct Checkpoint<'db> {
49 inner: *mut ffi::rocksdb_checkpoint_t,
50 _db: PhantomData<&'db ()>,
51}
52
53impl<'db> Checkpoint<'db> {
54 /// Creates new checkpoint object for specific DB.
55 ///
56 /// Does not actually produce checkpoints, call `.create_checkpoint()` method to produce
57 /// a DB checkpoint.
58 pub fn new<T: ThreadMode, I: DBInner>(db: &'db DBCommon<T, I>) -> Result<Self, Error> {
59 let checkpoint: *mut ffi::rocksdb_checkpoint_t;
60
61 unsafe {
62 checkpoint = ffi_try!(ffi::rocksdb_checkpoint_object_create(db.inner.inner()));
63 }
64
65 if checkpoint.is_null() {
66 return Err(Error::new("Could not create checkpoint object.".to_owned()));
67 }
68
69 Ok(Self {
70 inner: checkpoint,
71 _db: PhantomData,
72 })
73 }
74
75 /// Creates a new physical RocksDB checkpoint in the directory specified by `path`.
76 ///
77 /// A checkpoint is a consistent, read-only view of the database at a specific
78 /// point in time. Internally, RocksDB creates a new MANIFEST and metadata files
79 /// and hard-links the relevant SST files, making the checkpoint efficient to
80 /// create and safe to keep for long-lived reads.
81 ///
82 /// This method uses the default `log_size_for_flush` value (`0`), which instructs
83 /// RocksDB to flush memtables as needed before creating the checkpoint. Forcing
84 /// a flush ensures that the checkpoint includes the most recent writes that may
85 /// still reside in memtables at the time of checkpoint creation.
86 ///
87 /// Forcing a flush may create new SST file(s), including very small L0 SSTs if
88 /// little data has been written since the last flush. Applications that create
89 /// checkpoints frequently or during periods of low write volume may wish to
90 /// control this behavior by using an API that allows specifying
91 /// `log_size_for_flush`.
92 ///
93 /// Note:
94 /// - Checkpoints are always SST-based and never depend on WAL files or live
95 /// memtables when opened.
96 /// - If writes are performed with WAL disabled, forcing a flush is required to
97 /// ensure those writes appear in the checkpoint.
98 /// - When using RocksDB TransactionDB with two-phase commit (2PC), RocksDB will
99 /// always flush regardless of the `log_size_for_flush` setting.
100 pub fn create_checkpoint<P: AsRef<Path>>(&self, path: P) -> Result<(), Error> {
101 let c_path = to_cpath(path)?;
102 unsafe {
103 ffi_try!(ffi::rocksdb_checkpoint_create(
104 self.inner,
105 c_path.as_ptr(),
106 DEFAULT_LOG_SIZE_FOR_FLUSH,
107 ));
108 }
109 Ok(())
110 }
111
112 /// Creates a new physical DB checkpoint in `path`, allowing the caller to
113 /// control `log_size_for_flush`.
114 ///
115 /// `log_size_for_flush` is forwarded to RocksDB's Checkpoint API:
116 /// - `0` forces a flush as needed before checkpoint creation, which helps the
117 /// checkpoint include the latest writes; this may create new SST file(s).
118 /// - A non-zero value:
119 /// - **Expected behavior** (once RocksDB bug is fixed): Only forces a flush
120 /// if the total WAL size exceeds the specified threshold. When a flush is
121 /// not forced and WAL writing is enabled, RocksDB includes WAL files in
122 /// the checkpoint that are replayed on open to reconstruct recent writes.
123 /// This avoids creating small SST files during periods of low write volume,
124 /// at the cost of additional checkpoint storage space for the copied WAL.
125 /// - **Current behavior** (RocksDB bug): Never flushes, regardless of WAL
126 /// size. The checkpoint will always include WAL files instead of flushing
127 /// to SST. See: <https://github.com/facebook/rocksdb/pull/14193>
128 ///
129 /// In practice, using a non-zero value means checkpoints may represent an
130 /// *older, fully materialized database state* rather than the instantaneous
131 /// state at the time the checkpoint is created.
132 ///
133 /// Note:
134 /// - If writes are performed with WAL disabled, using a non-zero
135 /// `log_size_for_flush` may cause those writes to be absent from
136 /// the checkpoint.
137 /// - When using RocksDB TransactionDB with two-phase commit (2PC),
138 /// RocksDB will always flush regardless of `log_size_for_flush`.
139 pub fn create_checkpoint_with_log_size<P: AsRef<Path>>(
140 &self,
141 path: P,
142 log_size_for_flush: u64,
143 ) -> Result<(), Error> {
144 let c_path = to_cpath(path)?;
145 unsafe {
146 ffi_try!(ffi::rocksdb_checkpoint_create(
147 self.inner,
148 c_path.as_ptr(),
149 log_size_for_flush,
150 ));
151 }
152 Ok(())
153 }
154
155 /// Export a specified Column Family
156 ///
157 /// Creates copies of the live SST files at the specified export path.
158 ///
159 /// - SST files will be created as hard links when the directory specified
160 /// is in the same partition as the db directory, copied otherwise.
161 /// - the path must not yet exist - a new directory will be created as part of the export.
162 /// - Always triggers a flush.
163 ///
164 /// # Examples
165 ///
166 /// ```rust
167 /// use rust_rocksdb::{DB, checkpoint::Checkpoint};
168 ///
169 /// fn export_column_family(db: &DB, column_family_name: &str, export_path: &str) {
170 /// let cp = Checkpoint::new(&db).unwrap();
171 /// let cf = db.cf_handle(column_family_name).unwrap();
172 ///
173 /// let export_metadata = cp.export_column_family(&cf, export_path).unwrap();
174 ///
175 /// assert!(export_metadata.get_files().len() > 0);
176 /// }
177 /// ```
178 ///
179 /// See also: [`DB::create_column_family_with_import`](crate::DB::create_column_family_with_import).
180 pub fn export_column_family<P: AsRef<Path>>(
181 &self,
182 column_family: &impl AsColumnFamilyRef,
183 path: P,
184 ) -> Result<ExportImportFilesMetaData, Error> {
185 let c_path = to_cpath(path)?;
186 let column_family_handle = column_family.inner();
187 let metadata = unsafe {
188 ffi_try!(ffi::rocksdb_checkpoint_export_column_family(
189 self.inner,
190 column_family_handle,
191 c_path.as_ptr(),
192 ))
193 };
194 Ok(ExportImportFilesMetaData { inner: metadata })
195 }
196}
197
198impl Drop for Checkpoint<'_> {
199 fn drop(&mut self) {
200 unsafe {
201 ffi::rocksdb_checkpoint_object_destroy(self.inner);
202 }
203 }
204}