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