Checkpoint

Checkpoint provides APIs for creating openable snapshots of a RocksDB database at a specific point in time. Checkpoints can be used for backups, replication, or creating read-only database copies.

Creating a Checkpoint Object

Create

static Status Create(DB* db, Checkpoint** checkpoint_ptr);

Creates a Checkpoint object for a database.

DB*

The database to create checkpoints from.

Checkpoint**

Output parameter for the created Checkpoint object.

Status

Returns OK on success.

Creating a Checkpoint

CreateCheckpoint

virtual Status CreateCheckpoint(
  const std::string& checkpoint_dir,
  uint64_t log_size_for_flush = 0,
  uint64_t* sequence_number_ptr = nullptr
);

Builds an openable snapshot of the database.

const std::string&

Absolute path where the checkpoint will be created. Directory must not exist.

uint64_t

If total log file size >= this value, a flush is triggered for all column families. 0 (default) always triggers flush. Archived logs are not included in the calculation.

uint64_t*

Optional output parameter set to a sequence number guaranteed to be in the checkpoint.

Status

Returns OK on success, NotSupported if db_paths or cf_paths use multiple directories.

How Checkpoints Work

SST and Blob Files: Hard linked if the checkpoint directory is on the same filesystem, copied otherwise
Other Files: MANIFEST and other required files are always copied
Consistency: Checkpoint represents a consistent point-in-time snapshot

Exporting Column Families

ExportColumnFamily

virtual Status ExportColumnFamily(
  ColumnFamilyHandle* handle,
  const std::string& export_dir,
  ExportImportFilesMetaData** metadata
);

Exports all live SST files of a specified column family.

ColumnFamilyHandle*

Column family to export.

const std::string&

Directory where SST files will be exported. Must not exist.

ExportImportFilesMetaData**

Output parameter with information about exported SST files.

Status

Returns OK on success.

Export Behavior

SST files are hard linked when export_dir is on the same partition as the database
SST files are copied when on different partitions
Always triggers a flush
export_dir is created by the API

Example: Creating a Checkpoint

#include "rocksdb/utilities/checkpoint.h"

using namespace ROCKSDB_NAMESPACE;

// Open database
DB* db;
Options options;
options.create_if_missing = true;
Status s = DB::Open(options, "/tmp/testdb", &db);
assert(s.ok());

// Write some data
s = db->Put(WriteOptions(), "key1", "value1");
assert(s.ok());

// Create checkpoint object
Checkpoint* checkpoint;
s = Checkpoint::Create(db, &checkpoint);
assert(s.ok());

// Create checkpoint
uint64_t sequence_number;
s = checkpoint->CreateCheckpoint("/tmp/checkpoint1", 0, &sequence_number);
assert(s.ok());

printf("Checkpoint created at sequence number %lu\n", sequence_number);

// The checkpoint is an openable database
DB* checkpoint_db;
s = DB::OpenForReadOnly(options, "/tmp/checkpoint1", &checkpoint_db);
assert(s.ok());

// Read from checkpoint
std::string value;
s = checkpoint_db->Get(ReadOptions(), "key1", &value);
assert(s.ok());
assert(value == "value1");

delete checkpoint_db;
delete checkpoint;
delete db;

Example: Conditional Flush

#include "rocksdb/utilities/checkpoint.h"

using namespace ROCKSDB_NAMESPACE;

DB* db;
Options options;
Status s = DB::Open(options, "/tmp/testdb", &db);

Checkpoint* checkpoint;
s = Checkpoint::Create(db, &checkpoint);

// Only flush if log files exceed 100MB
uint64_t log_size_threshold = 100 * 1024 * 1024;
s = checkpoint->CreateCheckpoint("/tmp/checkpoint2", log_size_threshold);

if (s.ok()) {
  printf("Checkpoint created\n");
} else {
  fprintf(stderr, "Checkpoint failed: %s\n", s.ToString().c_str());
}

delete checkpoint;
delete db;

Example: Exporting a Column Family

#include "rocksdb/utilities/checkpoint.h"

using namespace ROCKSDB_NAMESPACE;

// Open database with column families
DB* db;
std::vector<ColumnFamilyHandle*> handles;
DBOptions db_options;
db_options.create_if_missing = true;

std::vector<ColumnFamilyDescriptor> column_families;
column_families.push_back(ColumnFamilyDescriptor(
    kDefaultColumnFamilyName, ColumnFamilyOptions()));
column_families.push_back(ColumnFamilyDescriptor(
    "new_cf", ColumnFamilyOptions()));

Status s = DB::Open(db_options, "/tmp/testdb", column_families,
                    &handles, &db);
assert(s.ok());

// Write to column family
s = db->Put(WriteOptions(), handles[1], "key1", "value1");
assert(s.ok());

// Create checkpoint object
Checkpoint* checkpoint;
s = Checkpoint::Create(db, &checkpoint);
assert(s.ok());

// Export column family
ExportImportFilesMetaData* metadata;
s = checkpoint->ExportColumnFamily(handles[1], "/tmp/export", &metadata);
assert(s.ok());

printf("Exported %zu SST files\n", metadata->files.size());

// Clean up
for (auto handle : handles) {
  delete handle;
}
delete metadata;
delete checkpoint;
delete db;

Use Cases

Database Backups

Checkpoints provide a fast way to create consistent backups:

Checkpoint* checkpoint;
Checkpoint::Create(db, &checkpoint);
checkpoint->CreateCheckpoint("/backups/" + current_timestamp());

Read Replicas

Create read-only copies for load distribution:

// Create checkpoint
checkpoint->CreateCheckpoint("/replicas/replica1");

// Open as read-only
DB* replica;
DB::OpenForReadOnly(options, "/replicas/replica1", &replica);

Testing and Development

Quickly create database copies for testing:

// Create checkpoint from production data
checkpoint->CreateCheckpoint("/test/testdb");

// Run tests against the checkpoint
runTests("/test/testdb");

Performance Considerations

Hard Links vs Copies

Hard links are nearly instantaneous
Copies can be slow for large databases
Ensure checkpoint directory is on the same filesystem for best performance

Flush Behavior

Setting log_size_for_flush > 0 can reduce checkpoint time
For most up-to-date snapshot, use log_size_for_flush = 0
Two-phase commit (2PC) always triggers flush regardless of setting

Space Efficiency

Hard-linked checkpoints use minimal additional disk space
Deleting the original database doesn’t affect hard-linked checkpoints
Space is only freed when all hard links are deleted

Limitations

Multiple Directories Not Supported

Checkpoints don’t support databases using db_paths or cf_paths with multiple directories (without WALs). The API will return NotSupported.

Sequence Number Guarantees

The sequence_number_ptr is set to a sequence number guaranteed to be part of the checkpoint, but not necessarily the latest sequence number.

Comparison with BackupEngine

Feature	Checkpoint	BackupEngine
Speed	Fast (hard links)	Slower (copies files)
Space efficiency	High (hard links)	Lower (full copies)
Incremental backups	No	Yes
Verification	No	Yes
Restore options	Simple	Advanced
Multiple backups	Manual management	Built-in
Metadata tracking	Manual	Automatic

Use Checkpoint for:

Fast point-in-time snapshots
Read replicas
Same-filesystem operations

Use BackupEngine for:

Incremental backups
Remote backups
Backup verification
Production backup workflows

Database

Read & Write

Transactions

Storage

Utilities

Creating a Checkpoint Object

Create

Creating a Checkpoint

CreateCheckpoint

How Checkpoints Work

Exporting Column Families

ExportColumnFamily

Export Behavior

Example: Creating a Checkpoint

Example: Conditional Flush

Example: Exporting a Column Family

Use Cases

Database Backups

Read Replicas

Testing and Development

Performance Considerations

Hard Links vs Copies

Flush Behavior

Space Efficiency

Limitations

Multiple Directories Not Supported

Sequence Number Guarantees

Comparison with BackupEngine

See Also

​Creating a Checkpoint Object

​Create

​Creating a Checkpoint

​CreateCheckpoint

​How Checkpoints Work

​Exporting Column Families

​ExportColumnFamily

​Export Behavior

​Example: Creating a Checkpoint

​Example: Conditional Flush

​Example: Exporting a Column Family

​Use Cases

​Database Backups

​Read Replicas

​Testing and Development

​Performance Considerations

​Hard Links vs Copies

​Flush Behavior

​Space Efficiency

​Limitations

​Multiple Directories Not Supported

​Sequence Number Guarantees

​Comparison with BackupEngine

​See Also

Creating a Checkpoint Object

Create

Creating a Checkpoint

CreateCheckpoint

How Checkpoints Work

Exporting Column Families

ExportColumnFamily

Export Behavior

Example: Creating a Checkpoint

Example: Conditional Flush

Example: Exporting a Column Family

Use Cases

Database Backups

Read Replicas

Testing and Development

Performance Considerations

Hard Links vs Copies

Flush Behavior

Space Efficiency

Limitations

Multiple Directories Not Supported

Sequence Number Guarantees

Comparison with BackupEngine

See Also