WriteOptions

Overview

The WriteOptions structure controls the behavior of write operations including Put(), Delete(), Merge(), and Write() (WriteBatch). It allows you to configure durability guarantees, write-ahead log behavior, and rate limiting.

Constructor

WriteOptions()
explicit WriteOptions(Env::IOActivity io_activity)
explicit WriteOptions(Env::IOPriority rate_limiter_priority,
                      Env::IOActivity io_activity = Env::IOActivity::kUnknown)

Options

bool

default:"false"

If true, the write will be flushed from the operating system buffer cache (by calling WritableFile::Sync()) before the write is considered complete. Writes will be slower but more durable.

sync=false: Similar crash semantics as the write() system call
sync=true: Similar crash semantics to write() followed by fdatasync()

If false and the machine crashes, some recent writes may be lost. If only the process crashes (without machine reboot), no writes are lost.

bool

default:"false"

If true, writes will not go to the write-ahead log, and the write may be lost after a crash.Important: The backup engine relies on write-ahead logs. If you disable WAL, you must create backups with flush_before_backup=true to avoid losing unflushed memtable data.

bool

default:"false"

If true and user is trying to write to column families that don’t exist (they were dropped), ignore the write instead of returning an error. If there are multiple writes in a WriteBatch, other writes will still succeed.

bool

default:"false"

If true and the write needs to wait or sleep, fails immediately with Status::Incomplete() instead of blocking.

bool

default:"false"

Mark this write request as lower priority if compaction is behind.

If no_slowdown = true: Request canceled immediately with Status::Incomplete()
If no_slowdown = false: Request will be slowed down (slowdown value determined by RocksDB)

bool

default:"false"

If true, this WriteBatch maintains the last insert positions of each memtable as hints in concurrent writes. Can improve write performance if keys in one WriteBatch are sequential.Ignored in non-concurrent writes (when concurrent_memtable_writes = false).

Env::IOPriority

default:"Env::IO_TOTAL"

Charge the rate limiter at the specified priority. Special value Env::IO_TOTAL disables charging the rate limiter.Currently covers automatic WAL flushes during live updates when disableWAL = false and manual_wal_flush = false.Only Env::IO_USER and Env::IO_TOTAL are allowed due to implementation constraints.

size_t

default:"0"

Number of bytes used to store protection information for each key entry. Currently supported values are zero (disabled) and eight.

Examples

WriteOptions options;
Status s = db->Put(options, "key1", "value");
assert(s.ok());

WriteOptions options;
options.sync = true;  // Ensure durability

Status s = db->Put(options, "key1", "value");
assert(s.ok());
// Data is guaranteed to be on disk

WriteOptions options;
options.disableWAL = true;  // Maximum performance, less durability

Status s = db->Put(options, "key1", "value");
assert(s.ok());

WriteOptions options;
options.no_slowdown = true;

Status s = db->Put(options, "key1", "value");
if (s.IsIncomplete()) {
  // Write would have blocked, handle accordingly
}

WriteOptions options;
options.low_pri = true;
options.no_slowdown = false;  // Allow slowdown instead of failing

Status s = db->Put(options, "key1", "value");
// Write may be slowed down if compaction is behind

WriteBatch batch;
batch.Put("key1", "value1");
batch.Put("key2", "value2");
batch.Delete("key3");

WriteOptions options;
options.sync = true;

Status s = db->Write(options, &batch);
assert(s.ok());

Durability vs Performance Trade-offs

Configuration	Durability	Performance	Use Case
Default (`sync=false`, `disableWAL=false`)	Good	Good	Standard operations
`sync=true`	Excellent	Low	Critical data that must survive crashes
`disableWAL=true`	Poor	Excellent	Temporary data, batch loads
`sync=true`, `disableWAL=true`	Invalid	-	Contradictory settings

Database

Read & Write

Transactions

Storage

Utilities

Overview

Constructor

Options

Examples

Durability vs Performance Trade-offs

See Also

​Overview

​Constructor

​Options

​Examples

​Durability vs Performance Trade-offs

​See Also

Overview

Constructor

Options

Examples

Durability vs Performance Trade-offs

See Also