18 Commits

Author	SHA1	Message	Date
zaidoon	553b52b4a7	Wire IndexFactory through block-based tables (#14963) ... Summary: Build block-based table indexes through `IndexFactory`, with modes for writing both indexes or only the custom index and a per-read index selector. Built-in reads retain their existing cache and prefetch paths. The review fixes preserve the existing UDI behavior at the migration and rollback boundaries: - Reopening an SST with index caching enabled reuses the serialized custom block. Each table reader constructs its own factory reader over those bytes and passes `NewReader()` a `Slice` view stored in the table reader. That view stays valid for the reader's lifetime, so a legacy reader can advance it or keep a pointer to it without changing the cached block. The view and the raw block are destroyed after the custom reader. - `IndexFactoryReader::ApproximateMemoryUsage()` keeps its documented meaning: the reader's own allocations, excluding the serialized block. `MemoryUsageIncludesIndexBlock()` defaults to false. A reader whose estimate includes the block opts in, and the wrapper subtracts the block size from that estimate. - Copying factory options and clearing a legacy UDI flag now rolls back that flag's policy. Legacy-derived options keep the requested default and resolve their effective mode without changing the inputs. Explicit factory modes retain precedence through cloning, failed updates, reconstruction, and the C API, including an explicitly selected `kStandardDefault`. - OK empty custom-index output still produces a zero-size meta block and reads through the full standard index. This covers point data and files containing only range tombstones. Custom-only mode rejects empty output because it has no standard fallback. - Default primary reads retain the table factory's precedence over a legacy per-read factory pointer. Explicit `kPreferCustom` still checks a supplied factory name; `kBuiltin` ignores that pointer. - OPTIONS files write equivalent legacy booleans for `kStandardDefault`, `kStandardRequired`, and `kCustomDefault`. Older releases retain those policies when loading newer files with `ignore_unknown_options=true`; the explicit-mode marker remains authoritative for current readers. Custom-only SSTs carry a footer feature bit so older readers reject them. Reject unsupported filter/index combinations before constructing filters. Trie size estimates account for shared prefixes, and block offsets or sizes beyond the 32-bit format limit return `NotSupported` instead of truncating. ## Safety and compatibility - Custom-only files require format version 6 or later and the factory. Rewrite every custom-only SST with a full standard index before removing the factory or downgrading. The other modes have no equivalent legacy configuration beyond the three listed above. - A raw C++ options struct cannot distinguish an explicitly assigned `kStandardDefault` from its default value. Configure the factory to make that choice explicit. `GetEffectiveIndexMode()` reports the resolved policy while preserving legacy inputs for copy-and-clear rollback. - A custom factory with user-defined timestamps is rejected in every mode except `kStandardOnly`, which ignores the factory. - Trie construction rejects a data-block offset or size greater than `UINT32_MAX`, including in `kStandardDefault`. That can fail flush, compaction, or `SstFileWriter::Finish()`; total SST size above 4 GiB alone is not the rejection condition. File-size targets do not split L0 or `SstFileWriter` outputs. - Custom-index cache hits, misses, and adds are reported under `BLOCK_CACHE_INDEX_*` instead of `BLOCK_CACHE_DATA_*`. The existing cache setting still controls ownership and cache use. - A table reader now charges a custom index block it owns (`cache_index_and_filter_blocks=false`); before, that block was not charged anywhere. Cached blocks are still charged only to the block cache. A reader whose `ApproximateMemoryUsage()` includes the serialized block, such as IntegerTrie or TimeSeries, must override `MemoryUsageIncludesIndexBlock()` to return true, or that block is charged twice. Pull Request resolved: https://github.com/facebook/rocksdb/pull/14963 Test Plan: For this commit, on macOS: `table_test`, `trie_index_test`, `trie_index_db_test`, and `block_based_table_reader_test` pass on the full stack (11,416 cases), and the full `table_test` passes at this PR's head alone (6,969 cases). The four custom-reader compatibility tests pass 100 times with `ASSERT_STATUS_CHECKED=1` and `COERCE_CONTEXT_SWITCH=1`, and 84 UDI table cases pass under ASAN with stack-use-after-return detection. Release-mode syntax checks with `-DNDEBUG -fno-rtti` on the changed sources, source checks, formatting checks, and `git diff --check` pass. Two new regressions cover the latest review, and both were checked failing before the fix: - `RetainedReaderSliceOutlivesTableOpen`: a reader keeps a pointer to the `Slice` it received, the stack is overwritten after open, and the reader then serves a seek and a full scan. It covers all three custom-index modes with owned and cached blocks, including a cached reopen. Without the fix, the retained `Slice` no longer matched the block. - `AuxiliaryReaderMemoryIsFullyCharged`: a reader that implements only the older reader methods reports a fixed allocation of half and twice the raw block size. Table usage must grow by that amount with owned and cached blocks, and a strict cache sized just below the required reservation must reject the open with `MemoryLimit`. Without the fix, usage fell short by `min(allocation, raw block size)` and the strict-cache open succeeded. The consuming-reader and strict-cache accounting tests are kept, now on shared helpers. From the previous revision: 498 focused C++ cases passed (82 table/factory, 156 trie, and 260 trie DB), along with the C API test and generated C API verification. Coverage includes both comparators, copied-options rollback, C factory reconstruction, explicit modes, OPTIONS serialization, SST Get/iteration, point and range-only flushes, compaction, reopen, cache disabled/enabled/evicted, and legacy factory precedence. The rollback, empty-output, primary-selector, and OPTIONS regressions were checked failing before their fixes. The cache test measures file reads at the custom block's actual offset: one on a cold open, zero on cached reopens, and one after eviction or with caching disabled. Disabling custom-block cache reuse makes that assertion fail. The full suite and Linux/Windows/TSAN coverage are left to CI. Earlier full-suite runs had failures/timeouts (173/2095 jobs normally and 152/2088 with Status checking); that broad suite was not rerun for this commit. ## Series Previous: https://github.com/facebook/rocksdb/issues/14962 (landed through import). Next: https://github.com/facebook/rocksdb/issues/14965. Reviewed By: jaykorean Differential Revision: D122796629 Pulled By: xingbowang fbshipit-source-id: 4c9d6f3f548c588a37b08fd94de25e8c0b5ef743	2026-10-21 20:20:38 -07:00
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
Peter Dillinger	c83a84e98c	Rename TableProperties::creation_time to oldest_ancestor_time (#15304) ... Summary: The `creation_time` table property has long stored the file's oldest ancestor time (the oldest key time among the file's ancestors, falling back to flush/compaction time), not the file's creation time, which is `file_creation_time`. A TODO in table_properties.h acknowledged the misleading name. This change starts the API migration: `TableProperties::oldest_ancestor_time` is the new name, and `creation_time` remains as a deprecated alias sharing storage via an anonymous union, so existing external reads and writes continue to compile and behave identically. An anonymous union is used rather than a `uint64_t&` alias member. A reference member would delete TableProperties copy/move assignment, make the implicit copy constructor bind the copy's alias to the source object (dangling), permit writes through a const TableProperties, add 8 bytes, and break the uint64_t-range walk in TEST_SetRandomTableProperties. The union leaves size, layout, copying, constness, and offsetof unchanged. Reading the other union member is formally UB in ISO C++, but both members are uint64_t and this is supported in practice by GCC, Clang, and MSVC. All in-repo uses of the old name now use `oldest_ancestor_time`. Names that are externally observable or persisted are intentionally unchanged: * On-disk property name `rocksdb.creation.time` (`TablePropertiesNames::kCreationTime`) * The `"creation_time"` key in TableProperties serialization (used by remote compaction) * The event-log JSON key and `TableProperties::ToString()` label * Java `TableProperties.getCreationTime()` and C `rocksdb_table_properties_creation_time()` C API: the auto-binding generator (tools/c_api_gen/auto_simple_bindings.py) only considered direct FieldDecls and failed on the anonymous union's implicit unnamed field. It now treats anonymous union members as direct fields. Regenerating adds a new C getter `rocksdb_table_properties_oldest_ancestor_time()` alongside the existing `rocksdb_table_properties_creation_time()`. Follow-up: remove the deprecated `creation_time` alias in a future release. Pull Request resolved: https://github.com/facebook/rocksdb/pull/15304 Test Plan: New unit test DBTablePropertiesTest.CreationTimeAliasesOldestAncestorTime verifies the two names share an address and that a write through the old name is visible through the new one. options_settable_test and compaction_service_test cover TableProperties serialization round trips through the unchanged "creation_time" key, now mapped to the renamed field. Reviewed By: jaykorean Differential Revision: D123079083 Pulled By: pdillinger fbshipit-source-id: 18b07d91f303a8f6de58da0c730f80d8c371505c	2026-10-05 10:34:04 -07:00
Josh Kang	c0512c4c34	Remove deprecated write_global_seqno ingestion support (#15287) ... Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/15287 `IngestExternalFileOptions::write_global_seqno` has been deprecated since RocksDB 8.0 and will soon be removed from the API. It requires ingestion to mutate SST files, sync them, regenerate checksums, and expose file-offset plumbing solely for that mutation. Remove the option and its C, Java, and `ldb` APIs. Assigned sequence numbers now live only in the MANIFEST, leaving newly ingested SST bytes and whole-file checksums unchanged. ## Backward Compatibility New readers continue to support existing SSTs containing a nonzero global sequence number written by legacy ingestion. Because that old write did not update the properties-block checksum, checksum verification retries against a temporary copy with only the global-seqno value restored to its original zero placeholder. The parsed sequence number and file contents remain unchanged. This fallback only accepts mismatches explained by the legacy rewrite. Other checksum failures continue through normal corruption handling, and `verify_checksums=false` continues to bypass verification. Reviewed By: xingbowang Differential Revision: D122405856 fbshipit-source-id: 934e9bc755d58ea8d84e1c085e9769015bd8dfd7	2026-10-05 09:53:52 -07:00
Peter Dillinger	b03a058d61	Persist more SST table properties for compression analysis (#15231) ... Summary: These changes improve the block-based SST table properties available for compression benchmarking and optimization. - Fix: `uncompressed_data_size` was computed while building a file but was never written to the properties block, so it always read back as 0. It is now persisted (written in AddTableProperty and read back in ParsePropertiesBlock). - Add: a new packed `lsm_info_at_creation` property records the LSM level and bottommost status at the file's creation. A new `LsmInfoAtCreation` struct owns the (extensible) uint64 encoding via symmetric Encode()/DecodeFrom(), keeping TableProperties a bare data struct. It distinguishes three states: "unknown" (nothing recorded, e.g. older files), "not applicable" (no LSM position, e.g. SstFileWriter/misc output), and "applicable" (level + bottommost, with an unknown-level sentinel for the DB repairer). The level is stored as its natural value. - Change: the `_compression_manager` detail in the `compression_options` property now records the manager's full serialized configuration (via ToString) instead of only its GetId(). New properties are additive and backward compatible: older files without them read back as "unknown"/0. Pull Request resolved: https://github.com/facebook/rocksdb/pull/15231 Test Plan: Added coverage in db/db_table_properties_test.cc: LsmInfoAtCreation encode/decode round-trips (natural levels, unknown level, not-applicable vs unknown); end-to-end persistence of uncompressed_data_size and lsm_info_at_creation after flush (L0, not bottommost) and a forced bottommost compaction; not-applicable recorded for an SstFileWriter file; and full compression manager configuration present in compression_options. Updated options/options_settable_test.cc for the new field. Also made table_test's BlockBasedTableTest.CompressionRatioThreshold resilient to per-file overhead changes (such as these added table properties): it now verifies the compression decision via the persisted data_size vs uncompressed_data_size rather than modeling total file size against a fixed overhead constant, which had become too tight. Full table_test passes. Reviewed By: rban1 Differential Revision: D120553038 Pulled By: pdillinger fbshipit-source-id: 07ede62dbcbe31c040fd9b037c7636a49558c4d9	2026-09-17 13:18:07 -07:00
Jay Huh	91b96f41cf	Retry the OpenAndCompact secondary open when the primary replaces CURRENT (#15179) ... Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/15179 A remote compaction worker (`DB::OpenAndCompact()`) opens the *live* primary's DB directory read-only, and that open reads `CURRENT`. The primary publishes each MANIFEST rotation by writing a new `CURRENT` under a temp name and renaming it over the old `CURRENT`. POSIX keeps an already-opened `CURRENT` readable after that replacement, but file systems without read-after-unlink semantics (remote or object stores) do not: the replaced object is reported as gone, surfacing in RocksDB as `IO error: No such file or directory` (`Status::PathNotFound`). The secondary open was not retried, so this transient race failed the whole compaction. There is an equivalent, already-recognized race one step later for the MANIFEST file (`ReactiveVersionSet::MaybeSwitchManifest()` converts it into `Status::TryAgain`), which was fatal here for the same reason. `DB::OpenAndCompact()` now retries the secondary open (up to 3 attempts) when it fails with `TryAgain` / `PathNotFound` / `NotFound` -- exactly the statuses a concurrent `CURRENT`/MANIFEST replacement produces. The retry limit is configurable via `OpenAndCompactOptions::max_secondary_open_retries`. Genuine failures are still returned after the bounded retries, and no safety check is weakened or skipped. Found by a `db_stress` crash test failure. Two non-default options in that run make this reachable and fatal: * `remote_compaction_worker_threads=8` with `remote_compaction_failure_fall_back_to_local=0` -- the latter was only recently randomized to 0; before that a remote compaction failure was always silently retried locally. Now `DbStressCompactionService::Wait()` maps the failure to `kFailure`, which becomes a sticky background error on the primary, so every subsequent `Flush()` returns it and `StressTest::ProcessStatus()` aborts with `assert(false)`. * `max_manifest_file_size=8192` -- the primary rotates MANIFEST (and therefore replaces `CURRENT`) constantly, which is what makes the race window hit in practice. Full chain: primary renames a new `CURRENT` over the old one -> the file system reports the replaced object as gone for the reader that already resolved it -> `GetCurrentManifestPath()` inside the worker's secondary open fails with `IO error: No such file or directory` -> `DB::OpenAndCompact()` returns that error with no retry -> `kFailure` (no local fallback) -> primary background error -> `Flush failed: IO error: No such file or directory: ... /CURRENT ...` -> assertion failure in `db_stress`. Reviewed By: joshkang97 Differential Revision: D118480192 fbshipit-source-id: a2618ee24e582e2e713af04464ee1e4038925ccb	2026-09-09 19:32:00 -07:00
Jay Huh	897162a6bc	Add session-scoped temporary directory for remote compaction (#15169) ... Summary: Remote compaction writes output SSTs into caller-selected job directories. If the primary crashes before installation or falls back to local compaction, those directories can outlive the DB session and accumulate under the DB directory. This change defines `kSessionTmpDirName` as `session_tmp`, the canonical name for a DB-local temporary directory whose contents have the lifetime of a DB session. The immutable boolean option `use_session_tmp_dir_for_remote_compaction` opts remote compaction into this directory. When enabled, an `OpenAndCompact()` directory name is resolved as `<dbname>/session_tmp/<job>`. During DB open, RocksDB creates the session temporary directory, completes recovery, and then synchronously deletes contents left by the previous DB session before scheduling compactions. `DestroyDB()` removes it as part of database deletion, and normal completion, failure, and cancellation paths clean the resolved per-job directory. The option defaults to false. Disabled callers retain the existing `<dbname>/<job>` layout and no session-directory cleanup. For rollout compatibility, legacy callers that already pass a DB-rooted output path are accepted unchanged only while the option is false. Directory creation and invalid-path errors are delegated to the configured filesystem rather than prevalidated by RocksDB. After D118301531 landed, per-job directory creation and resumption cleanup are kept together in `InitializeCompactionWorkspace()`. `OpenAndCompact()` resolves the client-provided name and expects DB open to have initialized the session temporary directory when the feature is enabled. The boolean is wired through C++ and generated C APIs, option serialization and reconstruction, `OpenAndCompact()`, ldb, db_bench, and db_stress. Tests cover path resolution, cross-session deletion, ownership boundaries, disabled behavior, `DestroyDB()`, configured compaction output, resumption fallback, and option round trips. Pull Request resolved: https://github.com/facebook/rocksdb/pull/15169 Reviewed By: pdillinger Differential Revision: D118227112 fbshipit-source-id: 01aa834b0b3f75638102130a86d95d537a2797bd	2026-09-02 21:46:24 -07:00
Peter Dillinger	e4a7136d3e	Preferred-phase scheduling for periodic (time-based) compaction ... Summary: `periodic_compaction_seconds` softly guarantees every SST is rewritten at least once per interval. Across a fleet of similarly-configured DBs, many events line those intervals up in lockstep -- a shared enable, a coordinated restart (e.g. DC power-outage recovery), or just similar write history -- so the periodic compactions all come due together, a recurring "thundering herd" that is especially painful with remote compaction (SEV S698635). The obvious fixes trade one problem for another. Spreading the herd out means some files get compacted off their natural schedule, which is wasted work; and a clumsy spread just relocates the herd or spawns a new one. So the real goal is narrow: **de-herd while keeping "badness" -- extra and/or late compaction -- small, and without inducing fresh herding at any step.** This change adds an EXPERIMENTAL, opt-in mechanism that gives each `(DB, column family)` a stable, well-spread *preferred phase* within the interval and steers periodic compactions toward it. It is randomized and *uncoordinated* (DBs never talk to each other), which both keeps it simple and, as it turns out, de-herds far more cheaply than adding jitter to the interval. It is controlled by a single mutable DBOption and is **off by default**: - `periodic_compaction_phase_recovery_percent` (default `0` = disabled / kill switch; recommended `33`; clamped to `[0, 100]`) -- how aggressively each trigger converges toward the phase, as a percent of the remaining gap, only ever pulling the trigger *earlier*. `0` reproduces the classic scheduler exactly; `100` jumps to the phase in one cycle; lower values approach gradually with much less extra work. The preferred phase itself needs no tuning: it is derived from the DB ID (stable across re-open and physical cloning/migration, but distinct across DBs) and each column family is offset from the DB's base phase, so the CFs of one DB don't fire together. (An earlier draft exposed a `compaction_schedule_seed` string option for choosing the phase source; it was over-engineered for the one behavior anyone needed, and as a mutable string it also broke OPTIONS-file round-trip verification in crash testing. It has been removed in favor of always using the DB ID.) ## The two kinds of badness "Badness" here is the fraction of compaction work that is ideally unnecessary: over-compaction (rewriting a file earlier than the interval required) plus a penalty for lateness (going overdue past the interval). Steady state is 0; both "never compact" and "compact twice as often as needed" approach 1. De-herding inherently spends a little badness to spread load out; every design choice below exists to bound one of those two costs *without* re-clustering the fleet. The scenario names cited in the design bullets below (`upgrade_dynamic_r33`, `naive_upgrade_r25`, `burst_r*`, `turndown_r33`, `turnup_r33`, ...) all come from the out-of-tree simulator; see its results page (the "Simulator and visualization" section below, with an interactive plot per scenario) for the evidence behind each claim. ## Design - **A stable per-(DB, CF) preferred phase = one fixed attractor per DB.** Each DB gets a base phase from its DB ID; each CF is offset from it. Because the target is fixed (not re-rolled each cycle) and unique per DB, the fleet converges to a uniform spread and then compacts *on time* -- badness decays toward ~0. This is the crucial contrast with naive per-cycle jitter, which de-herds but never stops jittering and so pays a permanent over-compaction cost (see `naive_upgrade_r25`: flat ~12-14%, only diffusive spreading) vs. `upgrade_dynamic_r33`, whose badness decays to ~0 for the same anti-herding. - **Converge gradually, and only ever earlier.** Each trigger closes a `recovery_percent` *fraction* of the gap to the phase, reaching it over a few cycles rather than in one burst, and never later than `periodic_compaction_seconds` in steady state. A lower rate does less extra work, which matters when the phase keeps moving (write-driven / bursty workloads), where a high rate wastefully "chases" it -- the burst sweep shows `burst_r25 < burst_r33 < burst_r50 < burst_r100` in sustained badness. `33` is the default balance: quick spreading, low extra work. - **Fractional recovery (not "snap") is latency-tolerant and doesn't re-herd.** Closing a fraction of the gap gives a single stable convergence point, so real-world scheduling/queueing latency -- the delay between a file becoming due and its compaction actually running -- merely shifts the whole fleet uniformly instead of re-clustering it. A tried "snap onto the phase when in range" variant converged a bit faster with no latency but re-herded around the snap threshold under latency; it was rejected. Graceful degradation beat peak speed. - **Spread a suddenly-due cohort instead of bursting it (bounded lateness).** Enabling the feature, turning `periodic_compaction_seconds` down, or catching up after downtime can leave a whole cohort past due at the same instant. Firing it all at once would just be the herd again, so such a cohort is spread over the first quarter-interval (~N/4) after the phasing anchor on an *absolute*, epoch-aligned per-(DB, CF) grid. This trades a bounded lateness (<= ~N/4 past the deadline, so the interval is a *soft* upper bound during these transients) for anti-herding, and the absolute grid keeps a rapidly restarting DB from being perpetually re-deferred and starved. `turndown_r33` shows the past-due cohort smeared over N/4 rather than bursting; `turnup_r33` confirms a turn-up creates no past-due cohort (deadlines only grow) and so no burst. For immediate enforcement at such a transition, trigger a manual compaction. - **Off by default, with a kill switch.** Inert unless `periodic_compaction_phase_recovery_percent > 0`; at `0` behavior is identical to the classic scheduler. ## Implementation notes - Phase math is integer-only (`Hash64` + `FastRange64`); floating point is avoided for its pitfalls. The per-CF offset is a golden-ratio (Weyl/Kronecker) additive sequence -- low-discrepancy for any number of CFs. - Logic lives in `db/periodic_compaction_phaser.{h,cc}` (`PeriodicCompactionPhaser`), which owns the recovery percent and the phasing anchor and exposes the stateless trigger-time math; `VersionSet` holds one and caches the per-CF result on each `Version`. The anchor is (re)set to now on DB open, on a recovery-percent change, and on any `periodic_compaction_seconds` change -- the three events that can create a past-due cohort. - Plumbed through the C API, `db_bench`, `db_stress`, and `db_crashtest`. ## Simulator and visualization (out-of-tree, not part of this change) A standalone simulator drives 40 real RocksDB instances through a real periodic-task scheduler, records every compaction (periodic vs write-driven), and scores the badness metric above across ~17 scenarios: dynamic/restart enable, interval turn-down/turn-up via `SetOptions`, on-cadence writes, random write bursts with a recovery-rate sweep, and the naive-jitter baseline. It is the basis for the numbers cited above. Interactive HTML (**NOTE** fb-internal URL sanitization might require you to copy-paste the URL yourself): 5759c6a62d/pc_phase_sim.html Reviewed By: jaykorean Differential Revision: D117487278 fbshipit-source-id: a62439548b7dd6fe7dfdbbe21b69531d8b57a1e8	2026-08-26 20:14:26 -07:00
Peter Dillinger	8f492b2f47	Store common user-key prefix once per block (format_version 8) (#15117) ... Summary: Building on D116105558, this change finishes and publishes `format_version = 8` as production-ready. The headline feature is a tweaked block encoding that stores the common user-key prefix shared by all keys in a block **once**, in the block's leading bytes `[0, restarts[0])`, instead of repeating it at every restart point. This shrinks prefix-heavy blocks (and their block-cache footprint) and, for bytewise-ordered keys, speeds up `Seek` by comparing prefix-stripped suffixes. It is applied to **data blocks** and **every index tier** (leaf/partition index, the partitioned-index top-level, and the partitioned-filter top-level). Motivation: MyRocks/ZippyDB/timeseries-style keys carry a long shared prefix (table/index id, partition, etc.). Repeating it at each restart wastes space and cache, and every Seek re-compares those bytes. Profiles show index-block seek CPU is comparable to data-block seek CPU (partitioned index does two index seeks per data seek), so index blocks are a first-class target, not just data blocks. ### Format (self-describing, no new footer bit) - The common prefix occupies the block's leading bytes; a non-zero `restarts[0]` (the offset of the first entry, i.e. the prefix length) self-signals its presence. `restarts[0]` is 0 in every block that does not use the feature (all versions, all block types), so a single fv8 reader transparently handles any mix of stripped and unstripped blocks -- no footer bit is consumed. - Previous versions would misinterpret this encoding by quietly ignoring the common prefix, which (along with the lack of extensibility in data-block metadata) is why it is gated behind format_version 8. - Only restart-point entries change on disk; non-restart entries are byte identical to fv7, so the writer produces the exact same bytes regardless of implementation. ### Public option New `BlockBasedTableOptions::optimize_key_common_prefix` (`enum class OptimizeKeyCommonPrefix`), default `kIfFastSeek`: - `kDisabled` -- never use it. - `kIfFastSeek` (default) -- use it only where it also enables the Seek speedup: format_version >= 8 with a built-in (reverse-)bytewise comparator. - `kEnabled` -- use it for all comparators at fv8; (reverse-)bytewise get space + fast seek, other comparators get the space savings only (the reader reconstructs full keys and compares with the real comparator). Expressed as a criteria so it need not be toggled per CF based on the comparator (which can vary by CF). It additionally requires `use_delta_encoding` (the feature builds on delta encoding) and `ts_sz == 0`; when `use_delta_encoding` is false -- the setting that also preserves zero-copy key pinning -- it is a no-op. Default format_version is unchanged (still 7); the feature is opt-in via fv8. ### Scope: every index tier The reader handles all index-like blocks uniformly (a non-zero `restarts[0]` self-signals a stripped block regardless of block type), so the writer strips the common prefix from every tier: - **Data blocks** and **leaf / partition index blocks**: enabled. - **Partitioned-index top-level block**: enabled. Under the default `index_shortening = kShortenSeparatorsAndSuccessor` the file's last separator would otherwise be a short successor sharing no leading bytes, collapsing the single-block top-level's common prefix to 0. When common-prefix is on the builder suppresses that one successor (keeps the full last key -- i.e. `kShortenSeparators` behavior for that one entry), so the top-level strips uniformly under every shortening mode; the full last key is also a tighter file upper bound, so it is not worse. - **Partitioned-filter top-level index**: enabled (same uniform treatment). Its space/CPU effect is small at default partitioning (the top-level filter index is tiny) but grows with many small partitions -- a filter miss short-circuits at, and is dominated by, the top-level filter-index seek (see Performance). Included for a uniform on-disk surface across tiers. Bloom filter *contents* still hash full user keys, so prefix/whole-key filtering is unaffected. ### Implementation - Writer (`block_builder.{h,cc}`): keys are encoded incrementally in the fv7 layout while the running common prefix is tracked cheaply (reusing the delta `shared`); at `Finish()` only the restart-point entries are rewritten in place with the prefix stripped, and the prefix is written once at the block start. The rewrite is generalized to the value-delta (fv4) index layout used by index blocks (no `value_size` header; bulk-copy the inline BlockHandle and non-restart entries verbatim). - Reader (`block.{h,cc}`, `dbformat.h`): `Block` decodes the prefix from `restarts[0]`; `BlockIter::ParseNextKey` prepends it on a restart point (`shared == 0`). The suffix-seek helpers (strip target once, compare shortened suffixes) live in the templated `BlockIter` base and are shared by data and index iterators (binary search, templated on `DecodeKey`/`DecodeKeyV4`); for non-bytewise comparators (data) and the hash `PrefixSeek` refine step, the reader reconstructs the probed restart key and compares full keys. - Gating (`block_based_table_builder.cc`, `index_builder.{h,cc}`, `partitioned_filter_block.{h,cc}`): the criteria is threaded to the data-block builder and to every index tier -- leaf/partition index, the partitioned-index top-level (`use_common_prefix_top`), and the partitioned-filter top-level -- together with the last-separator successor suppression (`ShortenedIndexBuilder::GetSeparatorWithSeq`) that lets the top-level strip under the default shortening mode. The index base gate also requires `super_block_alignment_size == 0` (block alignment can trigger `skip_delta_encoding`, producing non-restart `shared == 0` entries the reader could not distinguish from stripped restart keys). - Memory: the per-block/per-iterator prefix is stored as a `uint32_t` length (the prefix is always at offset 0) rather than a full `Slice`, and `Block` / `BlockBuilder` members were repacked so the feature adds little or no struct size. - Java: a new `OptimizeKeyCommonPrefix` enum and a `BlockBasedTableConfig` getter/setter, plumbed through JNI in both directions (the `newTableFactoryHandle` writer and the options-reconstruction constructor). ### Whole-file (table-level) prefix: investigated and rejected A natural extension is to store the whole-file common prefix once per *file* (when an `SstPartitioner` guarantees every key in the file shares a fixed prefix) instead of once per *block* -- e.g. the MyRocks index/table id, or a future 128-bit global id. It was prototyped end-to-end (partitioner-provided prefix captured at file open, stored in a `user_key_common_prefix` table property, and stripped from every data/index block; the reader re-prepends it) and then dropped. The `user_key_common_prefix` table property reserved in the previous diff is dropped in this one. The rationale, in case it is revisited: - Marginal benefit over per-block. Per-block already strips the full shared prefix from every key; the only thing whole-file removes on top is the single per-block copy of that prefix, i.e. `~= prefix_len / block_size` of the uncompressed (block-cache) footprint, with no meaningful read-CPU change (per-block already delivers strip-once + suffix compares). Measured at prefix_len=12, 4 KB blocks this was ~-0.3% incremental space; at the 8-16 KB data blocks typical of the space-constrained target (MyRocks/UDB) it is ~0.1-0.2% even with a 16-byte global id -- a fraction of a percent, seen only by partitioner users. Small block-size workloads are becoming more niche, and even where they exist, they are also CPU-sensitive (see next paragraph). - Real, if small, CPU tax on the *per-block* path. Reconstructing a key from two non-contiguous parts (file prefix + block residual) cost ~0.5-1.0% additional retired instructions on the per-block read path (deterministic across gcc and clang), wall-clock-neutral in cache-resident tests but present even when no whole-file prefix is configured. Attempts to remove it did not pan out: a compile-time specialization of the reconstruction *increased* instructions (+2.9%) by defeating inlining; a per-block combined-prefix buffer trades the CPU cost for a memory cost on every (default) block; and a per-iterator buffer was the original larger regression. Only invasive iterator-level monomorphization would truly zero it, which is not justified on this hot path. - Decision. A fraction-of-a-percent, partitioner-only space win does not justify a permanent per-block-read-path CPU tax plus additional on-disk format surface (a table property that changes whole-file interpretation). Dropped. The generic `SstPartitioner::ShouldPartitionByPrefix` hook is kept (cheap, and useful independently), and the reserved `user_key_common_prefix` table property is removed since no writer will emit it. ### Performance (db_bench, release/native, cache-warm, best-of-3, pinned) Three arms: (A) fv7 on the base/main branch, (B) fv7 with this change (should be neutral / byte-identical writing), (C) fv8 with this change and `optimize_key_common_prefix=enabled` (the optimization is active). Partitioned index + filters; `compression_type=none`, so SST bytes are the uncompressed block-cache footprint. `int` = db_bench default keys (variation-early, near worst case); `pfxN` = an N-byte shared prefix + varying suffix (MyRocks-like). Setup: `num=3,000,000`, `reads=1,500,000`, single thread, `metadata_block_size=4096`, cache holds the working set, pinned to one core. | shape (key/val) | arm | SST bytes | readrandom us/op | seekrandom us/op | |---|---|---:|---:|---:| | int (32/8) | A fv7 main | 138,983,658 | 3.484 | 4.995 | | | B fv7 ours | 138,983,146 | 3.518 | 5.024 | | | C fv8 ours | 137,681,420 | 3.490 | 4.986 | | pfx24 (32/8) | A fv7 main | 71,697,531 | 3.417 | 5.561 | | | B fv7 ours | 71,698,043 | 3.448 | 5.579 | | | C fv8 ours | 65,578,236 | 3.284 | 5.386 | | pfx56 (64/16) | A fv7 main | 102,942,266 | 3.624 | 5.830 | | | B fv7 ours | 102,942,266 | 3.678 | 5.835 | | | C fv8 ours | 90,554,642 | 3.444 | 5.626 | fv8 vs fv7-main (C vs A) -- space / readrandom / seekrandom: - int (32/8): **-0.9%** / ~neutral / ~neutral - pfx24 (32/8): **-8.5%** / **-3.9%** / **-3.1%** - pfx56 (64/16): **-12.0%** / **-5.0%** / **-3.5%** fv7-ours vs fv7-main (B vs A): SST bytes byte-identical (within 512 B; the fv8 paths are gated off), read/seek us/op within run-to-run noise (~1%, best-of-3 on a shared host). Net: fv8 is a space **and** read/seek-CPU win on prefix-heavy data and neutral on variation-early (`int`) data, so `kIfFastSeek` is safe on by default at fv8. ### Space by tier (compression=none, num=3M, mdb=4096; fv7 -> fv8) Where the win comes from -- the index tiers strip the most: | shape | data | leaf/partition index | top-level index | filter | |---|---:|---:|---:|---:| | int | -0.8% | -29% | -45% | -0.2% | | pfx24 | -8.3% | -69% | -89% | -0.8% | | pfx56 | -11.1% | -83% | -96% | -1.6% | Data bytes dominate the absolute total, but every index tier is stripped: leaf/partition index -29% to -83% and the partitioned-index top-level -45% to -96%. Filter *blocks* barely move (-0.2% to -1.6%) because filter bits hash full user keys; only the small top-level filter index is stripped. ### Point-miss lookups (readmissing) A partitioned-filter miss short-circuits at the filter (no data-block read), so it is dominated by the top-level filter-index seek plus the partition bloom. At a typical `metadata_block_size=4096` (few partitions, tiny top-level filter index) fv8 is neutral on misses (int +0.9%, pfx24 -1.0%, pfx56 -0.7% us/op -- all noise). The top-level-filter stripping pays only with many small partitions: at `metadata_block_size=256` it is pfx24 1.166->1.138 (**-2.4%**) and pfx56 1.273->1.188 (**-6.7%**) us/op. ### Backward / forward compatibility - Default `format_version` remains 7; the feature is inert unless a CF opts into fv8. Older RocksDB rejects fv8 files at footer decode (fail-safe). - Within fv8, the stripped-block set a writer can emit is fixed and every fv8 reader can read it (the `restarts[0]` signal plus uniform reader handling), so the on-disk surface is self-consistent across builds/downgrade. ### Follow-ups (not in this change) - Suffix-aware interpolation / hash index seek (currently correct via the reconstruction fallback, not perf-tuned). Pull Request resolved: https://github.com/facebook/rocksdb/pull/15117 Test Plan: - New focused unit tests (`table_test`), run at the full `format_version` matrix including the now-supported fv8: `GeneralTableTest.OptimizeKeyCommonPrefix` (data-block space+read+Seek correctness: existing and missing keys straddling the prefix, before/after-all, SeekForPrev), `OptimizeKeyCommonPrefixNonBytewise` (reconstruction path), and `IndexBlockCommonPrefixEquivalence` across `{kBinarySearch, kBinarySearchWithFirstKey, kHashSearch, kTwoLevelIndexSearch}` x `{partitioned filters}` x `{bytewise, reverse-bytewise}` (so both top-level tiers -- partitioned-index and partitioned-filter -- are exercised), asserting identical reads and a shrunken fv8 index. - The randomized `ParameterizedHarnessTest` now runs at fv8 (reverse-bytewise, restart intervals `{1,16,1024}`, special/empty keys fuzzed against the feature). - `db_crashtest.py` randomizes `format_version` including 8 and `optimize_key_common_prefix` in {0,1,2}. - Removed the reserved-property carve-out: dropped the `ReservedUserKeyCommonPrefix` reader test and the C API getter for the property; C API regenerated via `tools/c_api_gen/` (`make regen-c-api`), and the intentional public-C-API removal is recorded in `tools/c_api_gen/api_compatibility_allowlist.json`. - Java: `BlockBasedTableConfigTest.optimizeKeyCommonPrefix` (default `kIfFastSeek`, plus set/get of every value). - `table_test` `FooterTests` updated for the now-published fv8 footer, whose metaindex-gap encoding stores the metaindex block size in 16 bits (the test caps that size for fv >= 8). - Manual verification: the db_bench runs in Performance above (three-arm space + read/seek CPU, per-tier byte breakdown via `sst_dump`, and `readmissing`); and `readrandom`/`seekrandom` with `--block_protection_bytes_per_key=8` find 100% of keys at both fv7 and fv8 (reconstructed keys pass per-key checksum). Reviewed By: xingbowang Differential Revision: D116365016 Pulled By: pdillinger fbshipit-source-id: 66f4b5c60ea4fe0ff48d34c98d191ba8ebdf0665	2026-08-20 17:32:41 -07:00
Peter Dillinger	e8554f1b11	Faster and safer MANIFEST recovery for remote compaction (OpenAndCompact) (#15133) ... Summary: Faster and safer MANIFEST recovery for remote compaction (OpenAndCompact) `DB::OpenAndCompact` (remote/distributed compaction) opens the target DB as a secondary and reconstructs the LSM state from the MANIFEST before running the requested compaction. Previously, point-in-time recovery would stat/open the SST (and blob) files referenced by the MANIFEST to classify them found/missing and materialize candidate versions, and eagerly load their table handlers. That is (a) a lot of unnecessary file operations and open latency, especially on remote/distributed storage, and (b) fragile: when a file referenced by the MANIFEST but not an input to the compaction was momentarily unavailable to the worker -- e.g. an obsolete file the primary had already deleted -- recovery could fail the job (surfacing as an incomplete "no valid result") or roll back to an earlier version, even though the compaction only needs its own input files, which the primary keeps referenced for the job's duration. This was seen as a flaky failure of CompactionServiceTest.BasicCompactions on aarch64, and reproduces on x86 under COERCE_CONTEXT_SWITCH. Efficiency + reliability: recovery for the OpenAndCompact path now trusts the MANIFEST. It reconstructs the current version from FileMetaData without stat-ing/opening files to classify them and without eagerly opening candidate-version table handlers, so it does far fewer file operations and never fails or rolls back over a file the compaction does not need. The compaction's input files are opened (and unique-id verified) on demand as it reads them. Correctness hardening: trusting the MANIFEST means the worker's own (possibly eventually-consistent) view of CURRENT/MANIFEST drives the reconstructed LSM shape, which feeds correctness-critical decisions (Compaction::IsBottommostLevel / KeyNotExistsBeyondOutputLevel). A worker that read a stale CURRENT (older MANIFEST), a truncated MANIFEST, or a MANIFEST with a corrupt/torn tail could reconstruct against an older LSM shape and silently drop keys that should be kept. To prevent this, the primary records the MANIFEST position (file number and size) it scheduled the compaction from and passes it in CompactionServiceInput as a floor. After recovery the worker compares the size of the maximal *valid* prefix it reconstructed -- which stops at any corrupt or torn record and at a partial atomic group at EOF, so tolerated tail garbage cannot inflate it -- against that floor, and refuses to compact against an older view (an older file number, or the same file number whose valid prefix is shorter), returning Status::Incomplete so the CompactionService can fall back to a local compaction. Accept-equal-or-later is safe by monotonicity: while the inputs stay locked (being_compacted), a later view can only have moved data further down, never resurrecting a shadowed value, so only an older view is unsafe. Single kill switch: both behaviors are bundled behind one signal and one option. Presence of the floor on the request (min_manifest_file_number != 0) couples on both trust-manifest recovery and the floor check in the worker; absence reverts the worker to the original point-in-time recovery with no floor check. A single mutable DBOption, remote_compaction_manifest_floor (default on), gates whether the primary populates the floor, so it is the one escape hatch that disables the entire new recovery path on a running DB via SetDBOptions if it ever misbehaves. The new CompactionServiceInput fields are wire-compatible in both directions (0 = not provided), so an old worker or an old primary simply behaves as if the switch were off. Follow-up: recovery is not yet strictly "open only the compaction's inputs". A limited number of non-input files are still opened by the bounded file-property sampling in Version::PrepareAppend -> UpdateAccumulatedStats (tolerating any that are missing), which today populates input FileMetaData::num_entries for compaction input-record-count verification. A natural follow-up is to record the needed per-file info (e.g. num_entries) in the MANIFEST so the worker can skip these auxiliary opens entirely; alternatively, source input num_entries from the worker's own read of its input table properties. Relatedly, the floor comparand is the recovered "maximal valid prefix" size, which today equals the MANIFEST file size but is defined to stay correct if a future MANIFEST format writes trailing padding/footer past the last record. Pull Request resolved: https://github.com/facebook/rocksdb/pull/15133 Test Plan: Added tests in compaction_service_test.cc: - RemoteCompactionMissingLowerFileTrustsManifest: a non-input file referenced by the MANIFEST is unavailable during a remote compaction; the job completes with correct results (fails without trust-manifest recovery). The underlying race also reproduces under COERCE_CONTEXT_SWITCH. - RemoteCompactionManifestFloorRejectsStaleView: inflate the floor so the worker's recovered MANIFEST is below it; assert the worker rejects, the job falls back to local, and a below-output deleted key stays deleted (no silent resurrection). - RemoteCompactionManifestFloorSendsPosition: a non-zero floor is attached and the worker accepts its equal-or-later view. - RemoteCompactionManifestFloorKillSwitchOff: with the option off, no floor is sent, the worker uses the original recovery, and a transiently-missing non-input file makes the job fail/roll back (the escape hatch reverts behavior). - RemoteCompactionManifestFloorMutable: SetDBOptions flips the option; the floor stops being attached and the worker skips the check. options_settable_test covers the new mutable DBOption. Crash test: remote compaction is already exercised (db_crashtest randomly enables remote_compaction_worker_threads, driving DB::OpenAndCompact), so with remote_compaction_manifest_floor defaulting on, the new recovery path is covered by the crash test by default -- no new crash-test plumbing is needed. The kill switch is intentionally left un-randomized (always on): turning it off re-enables the original, occasionally-broken recovery, which would only add noisy failures for no benefit. UPDATE: crash test is not well covered because of `"remote_compaction_failure_fall_back_to_local": 1` which is masking other existing failures. Addressing this is a high-priority follow-up item. (Not practical to fix in this diff.) Reviewed By: jaykorean Differential Revision: D116738823 Pulled By: pdillinger fbshipit-source-id: c02e0a437d62fc526dbbfcf70edf43434dfc7c1f	2026-08-20 16:07:48 -07:00
Peter Dillinger	021374c62c	Start format_version=8 development toward new features (#15104) ... Summary: format_version background: SST files are shared across RocksDB versions. format_version is a critical tool in ensuring prior (and later) versioned readers do not misinterpret a file created by some version. Opt-in features can sometimes rely on previously-rejected corners of the schema space, but not always. This change: lands much of the format_version=8 (fv8) format surface as an internal-only draft -- readable and testable but not user-writable -- so upcoming features can build on a stable base. fv8 is NOT published: kLatestBbtFormatVersion stays 7, and reading or writing fv8 is gated behind the existing TEST-only TEST_AllowUnsupportedFormatVersion() hook. Publishing fv8 (raising the ceiling) is deferred to a later change. The pieces of fv8 added here, and what each unlocks: - Index value-delta escape. Existing behavior: index blocks (format_version >= 4) store each block handle as a delta against the previous entry's handle, and signal "this value is a full handle instead" by reusing the key sentinel `shared == 0`. Because the two are coupled, an index entry whose handle is not contiguous with the previous one must be forced to a restart, costing a full key as well as a full value. fv8 decouples them with an in-value escape codepoint: varint 0 means "a full BlockHandle follows," and genuine size deltas are remapped to zigzag(delta)+1 so that 0 stays free. A non-contiguous entry can then remain an ordinary key-delta-encoded, on-cadence entry. The escape applies to every index-shaped block, which includes the top-level index of index partitions and the index of filter partitions, not just the index over data blocks. Unlocks: the upcoming optimize_key_common_prefix index feature (removes its need to special-case super_block_alignment) and value-delta encoding for embedded-blob SSTs (previously disabled outright because interleaved blob records break handle contiguity). Guarded strictly on fv8; format_version <= 7 encoding and decoding are byte-for-byte unchanged. Note that restart points must not delta-encode, so they still have full values without a sentinel. - Data block footer bit 30 is reserved as an "extended metadata present" escape. Decode rejects a set bit as unsupported/corrupt at all versions. Unlocks: adding block-level metadata in the future through the one shared footer decoder, without another format_version bump or plumbing format_version into every block parser. (Older reader versions relied on this bit being zero for some integrity/consistency checking; format_version bump now makes it safe to use.) - Footer metaindex gap. For fv8, the top 16 bits of the footer's 4-byte metaindex-size field record the gap (in bytes) between the end of the metaindex block and the start of the footer; the low 16 bits hold the metaindex block size. Unlocks: a space very near the end of the file to save full file checksum state, for a "files carry their own checksums" feature that doesn't require SST parsing to extract the checksum states (to run them to completion on the trivial file tail). - Reserved "user_key_common_prefix" table property. The reader returns NotSupported when it is present and non-empty. Unlocks: a future whole-file optimization that stores the common prefix of all user keys once instead of in every restart key; until implemented, fv8 readers refuse such a file rather than mis-read it. - Because of the problem of inferring such a prefix at the start of constructing an SST file, we expect it will rely on SstPartitioner. Here we've added SstPartitioner::ShouldPartitionByPrefix() (not yet used) that will enable this optimization, and avoid the overhead of a virtual callback to SstPartitioner on every key written to an SST file. Supporting cleanups: the Footer's "unset" format_version sentinel is named (kInvalidFormatVersion) and the FormatVersionUses*() predicates assert against it, as each is a `version >= N` test that an unpopulated Footer would silently satisfy. Index block reader entry points (Block::NewIndexIterator() and friends) drop their defaulted trailing arguments so each caller states which codec it expects, and BlockBuilder::Add() takes delta_value by const reference rather than a pointer whose null case no caller used. Pull Request resolved: https://github.com/facebook/rocksdb/pull/15104 Test Plan: New unit tests, all exercising fv8 through TEST_AllowUnsupportedFormatVersion(): - block_test: value-delta escape codec round-trip (delta 0, negative, large, and the escape; asserts format_version <= 7 bytes match the legacy encoding and a legacy 0x00 still decodes as delta 0), and rejection of footer bit 30 at all versions. - db_flush_test: fv7-vs-fv8 read equivalence for super_block_alignment, including the separate_key_value_in_data_block intersection, confirming padding events (hence escape entries) occur and fv8 index values are delta encoded. - sst_file_reader_test: fv7-vs-fv8 read equivalence for embedded-blob SSTs, confirming fv8 (unlike fv7) delta-encodes their index values and actually emits escape entries (counted through a sync point). - block_based_table_reader_test: a builder+reader test that injects a footer metaindex gap via a sync point (verifies the gap bytes are written and the reader locates the metaindex via the recorded gap, and that too large a gap surfaces as a builder error), and that a non-empty reserved user_key_common_prefix property makes the reader return NotSupported. - table_test: two-level index with partitioned filters and index_block_restart_interval > 1, the configuration in which both top-level indexes delta-encode their values; verifies scan and point lookup round trips at each tested format_version including fv8. - (Not strictly fv8) Basic SstPartitionerFixedPrefix tests in slice_test (ShouldPartition, ShouldPartitionByPrefix, their mutual consistency, and CanDoTrivialMove), which had no non-DB coverage before. fv8 is also added to the table_test harness (GenerateArgList) and the shared footer version set (test::kFooterFormatVersionsToTest), so the existing table-level and DB-level property/checksum suites now also run at fv8. And added to crash test (minor revisions to db_stress). ## Performance details Release db_bench (PORTABLE=0, -march=native) A/B/C on the read/write fast path, comparing (a) parent, (b) this commit @ fv7, (c) this commit @ fv8. All DBs on tmpfs, 20M keys, block_size=2048, compression=none. Note index_block_restart_ interval=16 (not the default 1) is required to actually exercise the fv7<->fv8 index value-delta codec -- with restart interval 1 every index entry is a full- handle restart and the changed path never runs (confirmed delta-value=1 via sst_dump). Reads single-thread + core-pinned, warm cache, interleaved/rotated rounds, paired deltas. Reads (readrandom + seekrandom, non-partitioned single ~1.9MB index block and partitioned index+filters): fv7->fv8 in the *same* binary is within noise on all four workloads (largest -1.0%, CIs cross zero). before->after (fv7 path) is also within noise; perf shows a deterministic +0.4-0.6% instructions/op from the added branches (the format_version>=8 value_delta_escape guard + refactored data-block footer decode), which is below the throughput noise floor. Writes (fillseq + compact total CPU): fv7->fv8 null. compact (which rewrites all index blocks) is null before->after. fillseq showed +3.5% CPU before->after, but perf attributes it entirely to cycles/IPC with *identical* instructions/op (+0.01-0.04%) -- a code-layout effect on the untouched memtable-insert loop, not this change. Sanity: any single throughput/CPU delta <~1% is within the build-to-build noise floor, measured directly by comparing two byte-identical binaries (swings up to ~0.9% reads; the pre-native/PORTABLE=1 build showed a spurious -1.85% that vanished under -march=native). Net: no measurable regression from fv8 draft; fv7 encoding/decoding byte-for-byte unchanged, only the noted sub-1% instruction bump on the shared read path. Reviewed By: xingbowang Differential Revision: D116105558 Pulled By: pdillinger fbshipit-source-id: ead776cdd396d497d47872c0956ea8c651c0d13f	2026-08-17 12:08:59 -07:00
Michael C Huang	276495843d	Add blob file writer buffer size option (#15061) ... Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/15061 Adds mutable ColumnFamilyOptions field `blob_file_writable_file_max_buffer_size` to cap blob-file WritableFileWriter buffers independently from DBOptions::writable_file_max_buffer_size. The default value is 0, which preserves existing behavior by inheriting the DB-wide writer buffer cap. Non-zero values apply to both flush/compaction blob writers and direct-write blob writers. Direct-write updates are propagated through DBImpl::SetOptions to newly opened blob files without requiring a DB restart. Also wires option parsing, dumping, db_bench, db_stress, crashtest, and release-note coverage. Reviewed By: xingbowang Differential Revision: D114979265 fbshipit-source-id: 3f764b797628eee0ce379110c1a1f8a16beb3fa2	2026-08-11 17:38:34 -07:00
Josh Kang	c64f682946	Fix IoUringBackend crash in ReadIOExecutor worker threads (#15020) ... Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/15020 Each read executor worker creates its own `IoUringBackend`, and Folly's I/O thread pool creates its worker threads and EventBases lazily. A successful calling-thread probe or `DB::Open()` therefore does not validate every worker. A later read can start a new worker; previously, an `IoUringBackend` initialization exception on that worker could escape startup and terminate the process. The previous 512-submit setup also allowed Folly's capacity retry to reduce the completion queue to 512 while retaining a 1024-entry submission queue, which the kernel rejects with `EINVAL`. Use a 256-submit limit so the 512-entry retry remains valid. Configure the shared read executor during `DB::Open()` through `DBOptions::read_io_executor_threads`, defaulting to one thread. The backend factory catches per-worker io_uring initialization failures and uses Folly's default backend. Each worker's thread-local availability marker starts false and is set true only after `IoUringBackend` construction succeeds. When construction fails, the marker remains false and `SubmitReadAsync()` performs the read synchronously. The executor's maximum thread capacity can be raised or lowered; `db_stress` requests eight threads for async DB APIs. To expose this degradation, `FSRandomAccessFile::SubmitReadAsync()` now reports whether the asynchronous path was used. `RandomAccessFileReader` increments the `FILE_SUBMIT_ASYNC_READ_FALLBACK` ticker for every submission that falls back to synchronous I/O, making the fallback visible through the DB's `Statistics`. Reviewed By: xingbowang Differential Revision: D114031018 fbshipit-source-id: 1b7f6c1cea693e5dd743ea1ada0fca1cf757b3f9	2026-07-30 11:18:08 -07:00
Peter Dillinger	bb77d17072	Make Flush() optionally wait for OnFlushCompleted (FlushOptions::listener_wait) (#14992) ... Summary: DB::Flush() with wait=true only waits until the flush result is committed (memtables removed from the immutable list). The EventListener::OnFlushCompleted callbacks run afterward, on the background flush thread, with the DB mutex released, and the waiter is only woken by a shared condition variable that many unrelated events also signal. As a result a Flush(wait=true) caller can return before -- or in the middle of -- its OnFlushCompleted callbacks. This surfaced as a flaky failure in the c_test table_filter_listener_metadata case, which asserts listener_state.flush_count == 3 immediately after Flush() returns (https://github.com/facebook/rocksdb/actions/runs/29976431449). It is also long-standing behavior that other tests have worked around with TEST_WaitForBackgroundWork(). This adds an opt-in FlushOptions::listener_wait (default false). When set together with wait=true, Flush() does not return until the OnFlushCompleted callbacks for the flushed memtables have finished. Default behavior is unchanged. Implementation: MemTableList gains a per-column-family num_pending_flush_notifications_ counter (guarded by the DB mutex). The background flush thread reserves a pending notification at flush-commit time -- before the mutex is released to run the callbacks -- and releases it after they return, in both the single-CF (FlushMemTableToOutputFile) and atomic (AtomicFlushMemTablesToOutputFiles) paths. WaitForFlushMemTables treats a CF as finished only when its normal predicate holds and the counter is zero. Because the memtables are removed and the counter incremented under one continuous mutex hold (and, for atomic flush, all CFs are reserved before the per-CF notify loop starts releasing the mutex), a listener_wait waiter can never observe the flush as finished before the callbacks complete. The counter is per-CF rather than per-flush, so a listener_wait waiter can wait somewhat longer than strictly necessary: under rapid flushing it may block until an unrelated, later flush's OnFlushCompleted on the same CF also drains (e.g. a waiter satisfied by GetEarliestMemTableID() advancing still waits for the whole CF's pending notifications). This can only over-wait, never return early, and is tolerated in favor of implementation simplicity; a per-memtable-id watermark could tighten it if it ever matters. To keep the counter balanced against future edits, the release uses an RAII Defer (runs on every exit path) and ~MemTableList asserts the counter has drained to zero; SubPendingFlushNotifications asserts against underflow. A reservation is taken only when a callback will actually fire (committed flush info non-empty, not a mempurge, CF not dropped, listeners registered). Also adds the C API rocksdb_flushoptions_set/get_listener_wait (regenerated via tools/c_api_gen) and a DBImpl::TEST_FlushMemTableWithListenerWait() helper. Pull Request resolved: https://github.com/facebook/rocksdb/pull/14992 Test Plan: New db_flush_test cases ListenerWaitWaitsForOnFlushCompleted and ListenerWaitAtomicFlushWaitsForAllOnFlushCompleted use a listener that blocks inside OnFlushCompleted plus spurious bg_cv_ wakeups to deterministically verify that Flush(wait=true, listener_wait=true) does not return until the callback (all CFs, for atomic flush) has finished; the atomic case guards the per-CF mutex-release gap in the notify loop. Converted existing racy/worked-around cases to the new option: c_test table_filter_listener_metadata, listener_test OnSingleDBFlushTest and MultiDBMultiListeners, and db_flush_test FireOnFlushCompletedAfterCommittedResult (the last previously relied on TEST_WaitForBackgroundWork()). The auto-generated C API roundtrip test covers the new flushoptions field. db_stress StressTest::TestFlush now sets listener_wait on a hard-coded 1 in 4 of its manual flushes (both the atomic and non-atomic branches), so the crash test exercises the new path with the DbStressListener registered. Reviewed By: jaykorean Differential Revision: D113425407 Pulled By: pdillinger fbshipit-source-id: 6fd0f5bc93fabaccd8010c2fead1d93c4c44ccfb	2026-07-24 09:36:04 -07:00
Peter Dillinger	755c104bca	Unify clang detection for the C API codegen and add make regen-c-api (#14994) ... Summary: `USE_CLANG=1 make check-c-api-gen` failed with "clang++ not found" because the staleness check and the Python generator detected clang inconsistently: the Makefile inspected the `$(CXX)` make variable (the fbcode clang path) while the generator read the `CXX` environment variable, which make never exports. More broadly, clang++ was detected in several ad hoc places with fragile heuristics (grepping the compiler path, duplicated fallback lists in shell and Python). Centralize clang++ detection in build_detect_platform as a single `CLANG_CXX`: - `CLANG_CXX` honors `$CXX` when it is itself clang (so CI's `CXX=clang++-21` is used), else takes the first clang++ on PATH (bare, versioned, or the Meta-internal clang++.par). `CXX` (when building with clang) and `CLANG_ANALYZER` now derive from `CLANG_CXX` instead of re-detecting. - Infer `USE_CLANG=1` when the compiler is clang, detected via the compiler's own `__clang__` predefined macro rather than matching the binary path (which false-positives, e.g. a home dir containing "clang"), and emit it so clang-specific Makefile logic is consistent. - Emit `CLANG_CXX` to make_config.mk and pass it explicitly to the codegen, so `make check-c-api-gen` works without requiring `USE_CLANG=1` and the generator never guesses. Add a first-class `make regen-c-api` target -- now the preferred regenerate command referenced by the generated banners and user-facing messages. The Python generators no longer detect clang themselves; `--clang` defaults to `clang++` for manual runs and is overridden by the Makefile with `CLANG_CXX`. Regeneration verifies the clang runs before writing any file, so a missing/broken toolchain aborts cleanly instead of leaving a partially regenerated tree. Make field discovery clang-version-independent: older clang (e.g. 15) spells field types fully qualified (`rocksdb::ReadTier`, `rocksdb::BlockBasedTableOptions::IndexType`) while the fbcode/CI clang (21) uses the bare `ReadTier` / `IndexType` the family tables expect. Strip the ROCKSDB namespace and enclosing-struct qualifiers so both agree; this is a no-op on newer clang, so checked-in output and CI are unaffected. Also escape the literal "generated" in the generator .py sources (they emit the marker but are not themselves generated) so tooling stops treating them as read-only generated files. Pull Request resolved: https://github.com/facebook/rocksdb/pull/14994 Test Plan: Manual verification (not covered by CI): - `make check-c-api-gen` now runs the staleness sub-check (instead of skipping) and passes in a default gcc build as well as with `USE_CLANG=1` on an fbcode host, since `CLANG_CXX` is always populated. - `ROCKSDB_NO_FBCODE=1 make regen-c-api` using a system clang 15 (clang++.par) produces output byte-identical to the checked-in files (generated with clang 21), and `check-c-api-gen` reports "up to date" -- confirming the namespace/struct stripping is version-robust and a no-op on clang 21. - `regen_all.py --clang /nonexistent` exits non-zero with a clear message and leaves the generated files untouched. - `make regen-c-api` is idempotent (no diff on a clean tree). - Confirmed the escaped `\x40generated` still emits `// generated` byte-for-byte in the regenerated c.h/c.cc/.inc. - Reviewed .github/workflows/pr-jobs.yml: the build-linux-clang-21-no_test_run job's `CXX=clang++-21 make check-c-api-gen` resolves `CLANG_CXX` to clang++-21 (honoring `$CXX`) rather than the container's stray bare clang++. Reviewed By: xingbowang Differential Revision: D113447462 Pulled By: pdillinger fbshipit-source-id: 91ca92d21a71a8b92f9ff57500a8cec91a884078	2026-07-23 15:50:16 -07:00
Ranjan Banerjee	0a2ba2a164	Add shared backup/checkpoint option bases [1/4] (#14945) ... Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/14945 First diff in a stack that lets `Checkpoint` and `BackupEngine` share one parallel copy/link infrastructure. Pure options refactor, no behavior change. Adds two shared option bases in `rocksdb/utilities/checkpoint.h`: `CheckpointOrBackupEngineOptions` (engine-level config) and `CreateCheckpointOrBackupOptions` (per-operation options). `CheckpointEngineOptions` / `CreateCheckpointOptions` derive from them for checkpoint; `BackupEngineOptions` / `CreateBackupOptions` derive from them for backup and keep their backup-only fields. Reviewed By: xingbowang Differential Revision: D111387916 fbshipit-source-id: d7efa528ac91fb00090130c9d2a671b13e934a82	2026-07-23 14:41:33 -07:00
Jay Huh	7c385f4441	Add license headers to generated C API fragments (#14985) ... Summary: Pull Request resolved: https://github.com/facebook/rocksdb/pull/14985 The Open Source Automated Checkup (T280493780) flagged the 27 generated `c_api_gen/c_generated_*.inc` fragments for missing the required copyright header ("Meta Platforms, Inc. and affiliates"). The fragments are emitted by the C API code generators, none of which wrote a header, so every regeneration reproduced the violation. Root-cause fix in the generators so regenerated output is compliant: - `tools/c_api_gen/generate_c_api.py` (`HEADER_BANNER`) - `tools/c_api_gen/auto_simple_bindings.py` (`auto_header_banner`) - `tools/c_api_gen/gen_roundtrip_tests.py` Each now emits the standard Meta dual-license block (matching `c_base.h` / `include/rocksdb/c.h`) ahead of the `// generated` marker, and the 27 checked-in `.inc` fragments are regenerated accordingly. The assembled `include/rocksdb/c.h` and `db/c.cc` already carry a top-level header, so `regen_all.py`'s inliner now strips each fragment's license block when inlining to avoid repeating it once per fragment; those two files are therefore unchanged. Also adds the header to `tools/gtest_parallel_repro.py`, the one non-`.inc` source file flagged by the checkup. Reviewed By: pdillinger Differential Revision: D113242908 fbshipit-source-id: 4d81d1355c8d8a35cbc4377dd9b21df901ad3cb7	2026-07-23 12:19:02 -07:00
zaidoon	1cec28d82d	Finish C API code generation (continues #14572) (#14868) ... Summary: This continues and finishes **https://github.com/facebook/rocksdb/issues/14572** ("Add semi-automated code generation for RocksDB C API bindings") by xingbowang. The original author is unavailable to finish it, so I've taken it over. **All 13 of the original commits are preserved** (this branch was created from the PR head and builds on top of it — `git log` shows the original `Xingbo Wang` authorship intact); my follow-up work is in the commits prefixed `C API codegen:`. The underlying design is unchanged and is the original author's: hand-written source templates (`tools/c_api_gen/c_base.h` / `c_base.cc`) plus two generators (auto-discovery from the C++ headers + a spec-driven generator) are inlined into a single, self-contained, `generated` `include/rocksdb/c.h` and `db/c.cc`. This grows the public C API by **668 functions** while keeping `c.h` a single includable header with no `-I` requirement (so `bindgen` and other FFI tools keep working unchanged). This branch reconciles the PR with ~4 months of `main` and addresses the outstanding review feedback (clang-tidy bot, the automated code review, the `c.h` self-containedness discussion, and pdillinger's points about `include/rocksdb` hygiene and `generated` marking). ## What changed on top of the original PR ### Reconciled with current `main` - Merged current `main` (conflicts were confined to the generated/test files) and regenerated. Reconciled the 14 C API functions `main` added since the merge-base (e.g. `rocksdb_set_db_options`, the backup-engine rate limiters, `memtable_batch_lookup_optimization`, `optimize_multiget_for_io`, …) and restored 5 enum constants that upstream had added by hand (`rocksdb_txndb_write_policy_*`, `..._index_block_search_type_auto`, `rocksdb_blob_cache_read_byte`). ### Maintainer feedback (pdillinger) - **No non-user-includable files in `include/rocksdb`.** Moved the hand-written templates out of `include/rocksdb/` and `db/` to `tools/c_api_gen/c_base.{h,cc}`. They were `#include`-ing generated fragments, which broke `make check-headers` and was shipped by `make install`. `include/rocksdb/` now contains only the user-facing, self-contained, `generated` `c.h`. - `c.h` / `c.cc` carry the `// generated` marker. ### Backward compatibility (zero ABI break) - The generator derived each wrapper's C type purely from the C++ field, which had silently changed **5 already-shipped signatures** (e.g. `rocksdb_writeoptions_disable_WAL` `int` → `unsigned char`). Added an ABI type-pinning layer (`tools/c_api_gen/abi_type_overrides.json`) so already-shipped functions keep their historical C signature (the body still casts to the real field type). A repo-wide diff against the merge-base now reports **0 ABI drift**. - New `check_api_compatibility.py` gate (wired into CI + `make`) fails on any removed/changed public function **or** removed enum/typedef symbol, vs a reference revision. Intentional changes go in an allowlist with a reason. ### Correctness (from the automated review) - Restored 5 option setters that were declared in `c.h` but **defined nowhere** (link failure for downstream bindings such as `rust-rocksdb`). Added `check_api_completeness.py` (dependency-free; runs in CI + `make`) asserting every declared function has exactly one definition — this is the gate that would have caught it. - `CopyStringVector` now null-checks `malloc`; the WAL filter `std::move`s the `WriteBatch`; the backup exclude-files callback captures by value instead of the wrapper pointer. ### Build / CI robustness - Removed the dead `C_API_CODEGEN_STAMP` Makefile prerequisite (it was a silent no-op). - The `make check` staleness check is now opt-out-able (behind `SKIP_FORMAT_BUCK_CHECKS`) and skips gracefully when `clang++` is unavailable, so `make check` works without the codegen toolchain. CI remains the authoritative gate. - Pinned `clang-format` consistently through `regen_all.py` / `verify_generated_up_to_date.py` (CI uses clang-format-21) so regeneration is byte-reproducible across environments. - Cleared all 20 `clang-tidy` warnings the bot reported on `db/c.cc` changed lines (fixed in the `c_base.cc` template, not the generated output). - Updated the internal Buck `c_test_bin` wrapper to expose generated `c_api_gen/*.inc` fragments as headers, so sandboxed Buck builds can compile `db/c_test.c` after the generated round-trip tests are included. ### Test coverage - Added `gen_roundtrip_tests.py`, which derives **462 set→get→assert round-trip checks across 25 option objects** from the same generated fragments and wires them into `db/c_test.c`. Coverage now tracks the generated surface automatically. ### Docs - Added the `unreleased_history/public_api_changes` note and fixed `claude_md/add_public_api.md`, which still told contributors to hand-edit the now-`generated` `c.h`/`c.cc`. Pull Request resolved: https://github.com/facebook/rocksdb/pull/14868 Test Plan: - `make c_test && ./c_test` — **passes**, including the 462 generated round-trip assertions (a successful link also confirms the API is complete). - `python3 tools/c_api_gen/check_api_completeness.py` — all 1737 declared functions defined exactly once. - `python3 tools/c_api_gen/check_api_compatibility.py --ref <release>` — 1070 reference functions + 229 enum/typedef symbols preserved, 0 removed/changed. - `python3 tools/c_api_gen/verify_generated_up_to_date.py` — generated output is stable. - `include/rocksdb/c.h` confirmed self-contained (only `<stdbool.h>`, `<stddef.h>`, `<stdint.h>`). cc xingbowang - `buck2 build --flagfile fbcode//mode/dev fbcode//internal_repo_rocksdb/repo:c_test_bin` — passes. - `buck2 build --flagfile fbcode//mode/dev --config fbcode.arch=aarch64 fbcode//internal_repo_rocksdb/repo:c_test_bin` — passes. Reviewed By: pdillinger Differential Revision: D109149150 Pulled By: xingbowang fbshipit-source-id: 3417375345f360a4c78bdfe27e9850b89d0a226a	2026-06-24 10:45:42 -07:00