Bucket catalog stripes, state registry and eras
Parent: Bucket catalog memory and closure reasons · Published reference · snapshot 2026-10-24 · skill mongodb-cohort-bd6489c69c3d
↓ Facts as markdownall context files
Source-anchored research for Bucket catalog stripes, state registry and eras. Run status: COMPLETED.
These notes link each claim to its source. Some citations identify archived research reports that are no longer hosted on this site. A published reference means the content is available; it does not certify independent review or accuracy.Read the editorial policy and follow the sources before relying on a claim.
How it works
- bucketsPerEra controls reclamation of clear history: when an era loses its last bucket, cleanup drops clear records at or before the oldest remaining bucket era, or all records when no bucket eras remain. An old bucket can therefore retain clear-history bookkeeping. (medium confidence) (verified as of 2026-10-24) [source]
- Cleared and frozen states block insertion, including their prepared variants. Frozen state persists when tracking is stopped; removing a bucket’s ordinary catalog representation therefore need not erase every registry entry. (high confidence) (verified as of 2026-10-24) [source]
Problems, failure modes and limitations
- The registry distinguishes normal, prepared, cleared, frozen, and combined prepared states. Direct writes use a counter; they conflict with insertion/reopening and cannot proceed against prepared buckets. The storage engine mediates conflicts among direct writers. (high confidence) (verified as of 2026-10-24) [source]
- SERVER-108039 documents unnecessary catalog-era increments when unrelated collections were dropped. SERVER-108089 documents stale-era retries that could exhaust reopening attempts and allocate a new bucket. Both tickets list 8.3.0-rc0 as a fix version; these are historical failure modes, not evidence that current master retains them. (medium confidence) (verified as of 2025-10-27) [source]
Comparisons and alternatives
- A Stripe owns open-bucket indexes, an idle-bucket list, an archived-bucket map and outstanding reopening requests. These tracked structures contribute to bucket-catalog memory; stripes partition synchronization rather than imposing a separate user-configurable memory budget. (medium confidence) (verified as of 2026-10-24) [source]
Facts and statements
- The master implementation guide describes 32 non-configurable lock stripes, with each metadata value consistently hashed to a stripe. Different metadata values can collide on a stripe and create contention. (low confidence) (verified as of 2026-10-24) [source]
- BucketStateRegistry spans stripes and protects its own state with a mutex. It stores per-bucket state or a direct-write counter, the current era, bucket counts per era and collection-clear records indexed by era. (high confidence) (verified as of 2026-10-24) [source]
- Collection clearing is asynchronous: clearSetOfBuckets increments the era and records collection UUIDs. Later state materialization checks clear records newer than a bucket’s lastChecked era and marks matching buckets cleared; unaffected buckets advance their lastChecked era. (high confidence) (verified as of 2026-10-24) [source]
- serverStatus.bucketCatalog.stateManagement exposes bucketsManaged, currentEra, erasWithRemainingBuckets, and trackedClearOperations. bucketsManaged includes direct-write conflict tracking; it is not simply the number of open bucket representations. (high confidence) (verified as of 2026-10-24) [source]
- SERVER-90672 documents a cross-stripe OID/state collision defect. MongoDB lists fixes in 7.0.16, 8.0.0-rc14, and 8.1.0-rc0; Percona's 2025-02-19 release notes confirm its 7.0.16-10 distribution includes the upstream fix. (high confidence) (verified as of 2026-09-21) [source]
- SERVER-108039 reports that dropping any collection could unnecessarily advance the catalog era. Before SERVER-108089, this could reject reopening and allocate another bucket; the issue says the later refresh fix removes that bucketing effect. This scopes era growth as a historical diagnostic signal, not proof of memory-driven closure. (low confidence) (verified as of 2025-10-27) [source]
- The diagnostics issue SERVER-98672 explicitly identifies era-mismatch reopening failures and deferred-cleared bucket removal as useful observability gaps. Its per-stripe bucket gauges were split into SERVER-105439, whose retrieved record remains unresolved; the proposal is not evidence that those gauges shipped. (high confidence) (verified as of 2026-07-07) [source]
- SERVER-77712 requests an architecture-guide explanation of BucketStateRegistry and its interaction with direct writes. Its retrieved record remains unresolved, so implementation code is necessary evidence for the detailed state model. (low confidence) (verified as of 2025-10-27) [source]
- The reviewed master implementation distributes bucket work across independently locked stripes; the implementation guide specifies 32 stripes with deterministic metadata hashing and no user configuration. This is an internal implementation detail, not a version-independent interface. (high confidence) (verified as of 2026-10-24) [source]
- Direct writes synchronize through registry counters. Completing the final direct write advances the era, so reopening can detect a potentially stale bucket even if it never observed the counter. initializeBucketState rejects an older target era with WriteConflict. (high confidence) (verified as of 2026-10-24) [source]
- appendStats exposes stateManagement.bucketsManaged, currentEra, erasWithRemainingBuckets and trackedClearOperations as map sizes or the era counter. These measure synchronization bookkeeping; currentEra is not a bucket-closure count. (low confidence) (verified as of 2026-10-24) [source]
- Percona’s 7.0.16-10 release notes, dated 2025-02-19, explicitly include upstream SERVER-90672 to prevent duplicate bucket OIDs within or across stripes. This establishes downstream inclusion of that fix, not independent validation of the entire registry design. (low confidence) [source]
Children
- No children recorded.