Xingbo Wang baa4d373a6 Commit authoritative OPTIONS file numbers in MANIFEST (#15305) ...

Summary:
Pull Request resolved: https://github.com/facebook/rocksdb/pull/15305

Why the change is required:

Column-family topology is durable in MANIFEST, while its operational
configuration snapshot is stored in a separate OPTIONS file.
CreateColumnFamily and DropColumnFamily previously committed MANIFEST first
and wrote OPTIONS afterward. An OPTIONS I/O failure could therefore make the
API report failure after the topology change was already durable.
Persisted-options readers also selected the highest file number and could
consume an orphan left by a failed publication.

Previous behavior:

RocksDB had no durable correspondence between a MANIFEST state and the
OPTIONS snapshot describing it. LoadLatestOptions and
GetLatestOptionsFileName treated the highest-numbered OPTIONS file as
authoritative. Column-family creation and deletion returned the later OPTIONS
persistence error even when their MANIFEST edit had already succeeded.
Multi-column-family operations wrote a complete OPTIONS snapshot after every
successful member, producing quadratic OPTIONS bytes.

Ordinary DB::Open consumes caller-supplied DB and column-family options rather
than loading OPTIONS. This change preserves that contract.

New behavior:

Add the default-disabled experimental DB option
track_options_file_number_in_manifest. Its value is serialized into each
OPTIONS file so the selection rule is self-describing and participates in the
normal DB-options compatibility checks.

When enabled, RocksDB first durably creates and renames OPTIONS-N and then
commits N with one safely ignorable MANIFEST field. A normal OPTIONS rotation
uses one MANIFEST commit. Column-family creation and deletion prewrite the
proposed snapshot and commit its number together with a topology edit in the
same VersionEdit. A failure before the OPTIONS file is durable changes no
topology. A failure after the file is durable but before MANIFEST commit leaves
an orphan that binding-aware readers ignore, while the previous committed
snapshot remains authoritative.

Each multi-CF create or drop writes one proposed snapshot, independent of the
batch size. Create commits the new number with the first successful add; drop
commits it with the last successful drop. Existing partial-success semantics
can therefore leave a committed snapshot with extra CFs, but never one missing
a live MANIFEST CF. Persisted-options APIs filter this safe superset against
recovered MANIFEST membership. A snapshot missing a live CF is corruption.
DB::Open with create_missing_column_families uses the same batched path.

If the newest OPTIONS file has tracking disabled, it retains the legacy
highest-numbered-file behavior, including after an old or disabled writer has
run. If it has tracking enabled, readers use the recovered MANIFEST commit and
reject newer tracked orphans. A missing usable commit falls back to the highest
tracked snapshot for RepairDB and legacy-rewrite recovery. DB open logs that
fallback through its configured logger; logger-less utility APIs remain
silent. Writable open removes rejected tracked orphans when local obsolete-file
deletion is enabled. Read-only open never mutates the DB directory.

A DB with no recovered commit and tracking disabled takes the legacy fast path
without parsing the newest OPTIONS file. When inspection is required, RocksDB
reads only the tracking marker. Marker-read failures used for selection do not
fail DB open; a recovered commit remains authoritative and ambiguous newer
candidates are conservatively retained.

The first topology change after enabling tracking first binds the current
topology, so failure of the proposed change cannot make its orphan
authoritative. MANIFEST failure during an ordinary tracked OPTIONS rotation
also enters the existing manifest-write background-error path.

Implementation:

- Add the safely ignorable CommittedOptionsFileNumber VersionEdit field and
  carry it through recovery, MANIFEST snapshots, rollover, and subset
  checkpoints.
- Persist the tracking marker through C++, C, and Java options, generated
  round-trip coverage, compatibility checking, and db_stress configuration.
- Centralize binding-aware selection for DB open and public persisted-options
  APIs. Reuse RecoveryContext's directory listing, use a narrow marker scan,
  and recover live CF names while replaying MANIFEST.
- Filter manifest-selected safe-superset snapshots to live MANIFEST CFs in
  LoadLatestOptions and compatibility verification without discarding their
  option maps.
- Prevalidate and sanitize CF batches outside the DB mutex, write one complete
  snapshot while options_mutex_ serializes topology changes, and hold the DB
  mutex only for the existing individual MANIFEST commits. Batch missing-CF
  creation during DB open follows the same locking boundary.
- Keep the committed snapshot live in cleanup and live-file APIs, and make
  subset checkpoints write an OPTIONS snapshot and filtered MANIFEST with
  identical membership in tracked and legacy modes.
- Preserve the first partial multi-CF drop error while consuming legacy
  OPTIONS persistence Status, and sync the checkpoint MANIFEST directory after
  replacement.
- Pass checkpoint helper callbacks by reference and group VersionEdit storage
  by alignment so the new paths add neither callback copies nor avoidable
  object padding.

Safety boundaries and unsupported cases:

- Tracking defaults to false. Disabled writers and never-tracked databases
  retain legacy write ordering and highest-numbered selection.
- Older binaries safely ignore the new MANIFEST tag and continue choosing the
  highest OPTIONS number. Downgrade is readable but not crash-atomic: an old
  binary can consume a tracked orphan. That is the same class of
  OPTIONS/MANIFEST inconsistency as the previous behavior.
- A rollback binary must know the serialized option name before the feature is
  enabled. Exact compatibility checks intentionally report a mismatch when the
  caller's tracking setting differs from the persisted snapshot.
- A newer untracked OPTIONS file deliberately supersedes an older committed
  number, allowing an old or disabled writer to become authoritative without
  rewriting MANIFEST.
- Reactive secondary and follower instances do not enforce or repair the
  binding. Ordinary DB::Open still uses caller-supplied options.
- Writable open does not delete rejected tracked or ambiguous files when a
  compaction service owns OPTIONS-file retention. Read-only open performs no
  repair writes.
- Direct consumers that scan OPTIONS filenames themselves are unchanged; the
  binding is enforced by RocksDB's persisted-options APIs.
- If the committed snapshot is missing and only tracked candidates remain,
  selection intentionally falls back to the highest candidate so RepairDB
  output remains usable.

Validation coverage and known limitations:

Focused coverage exercises encoding compatibility, tracked and legacy
selection, the never-tracked open fast path, marker-read failures, exact
tracking-marker compatibility, activation and disable/re-enable transitions,
batched create/drop and create-missing behavior, partial-batch safe supersets,
OPTIONS/MANIFEST failure injection, background-error propagation, orphan
cleanup and retention, read-only non-mutation, subset-checkpoint behavior,
stale OPTIONS recovery, RepairDB option sanitization, and transient
read-corruption reconstruction. The assertion-enabled full executable suite
passes. The repository check-format and check-sources wrappers cannot run
because they invoke Git inside this Sapling checkout; fbsource lint is used
instead. Cross-platform CI is not part of local validation.

Reviewed By: pdillinger

Differential Revision: D123104845

fbshipit-source-id: 77d94c989243c3f3f9fedfa81fa364c166250303

2026-10-11 10:39:30 -07:00

29 KiB

Raw Permalink Blame History

View Raw