Line data Source code
1 : // Copyright 2011 The LevelDB-Go and Pebble Authors. All rights reserved. Use
2 : // of this source code is governed by a BSD-style license that can be found in
3 : // the LICENSE file.
4 :
5 : package pebble
6 :
7 : import (
8 : "bytes"
9 : "fmt"
10 : "io"
11 : "runtime"
12 : "sort"
13 : "strconv"
14 : "strings"
15 : "time"
16 : "unicode"
17 :
18 : "github.com/cockroachdb/crlib/fifo"
19 : "github.com/cockroachdb/errors"
20 : "github.com/cockroachdb/pebble/internal/base"
21 : "github.com/cockroachdb/pebble/internal/cache"
22 : "github.com/cockroachdb/pebble/internal/humanize"
23 : "github.com/cockroachdb/pebble/internal/keyspan"
24 : "github.com/cockroachdb/pebble/internal/manifest"
25 : "github.com/cockroachdb/pebble/internal/testkeys"
26 : "github.com/cockroachdb/pebble/objstorage/objstorageprovider"
27 : "github.com/cockroachdb/pebble/objstorage/remote"
28 : "github.com/cockroachdb/pebble/rangekey"
29 : "github.com/cockroachdb/pebble/sstable"
30 : "github.com/cockroachdb/pebble/sstable/blob"
31 : "github.com/cockroachdb/pebble/sstable/block"
32 : "github.com/cockroachdb/pebble/sstable/colblk"
33 : "github.com/cockroachdb/pebble/vfs"
34 : "github.com/cockroachdb/pebble/wal"
35 : )
36 :
37 : const (
38 : cacheDefaultSize = 8 << 20 // 8 MB
39 : defaultLevelMultiplier = 10
40 : )
41 :
42 : // Compression exports the base.Compression type.
43 : type Compression = block.Compression
44 :
45 : // Exported Compression constants.
46 : const (
47 : DefaultCompression = block.DefaultCompression
48 : NoCompression = block.NoCompression
49 : SnappyCompression = block.SnappyCompression
50 : ZstdCompression = block.ZstdCompression
51 : )
52 :
53 : // FilterType exports the base.FilterType type.
54 : type FilterType = base.FilterType
55 :
56 : // Exported TableFilter constants.
57 : const (
58 : TableFilter = base.TableFilter
59 : )
60 :
61 : // FilterWriter exports the base.FilterWriter type.
62 : type FilterWriter = base.FilterWriter
63 :
64 : // FilterPolicy exports the base.FilterPolicy type.
65 : type FilterPolicy = base.FilterPolicy
66 :
67 : // KeySchema exports the colblk.KeySchema type.
68 : type KeySchema = colblk.KeySchema
69 :
70 : // BlockPropertyCollector exports the sstable.BlockPropertyCollector type.
71 : type BlockPropertyCollector = sstable.BlockPropertyCollector
72 :
73 : // BlockPropertyFilter exports the sstable.BlockPropertyFilter type.
74 : type BlockPropertyFilter = base.BlockPropertyFilter
75 :
76 : // ShortAttributeExtractor exports the base.ShortAttributeExtractor type.
77 : type ShortAttributeExtractor = base.ShortAttributeExtractor
78 :
79 : // UserKeyPrefixBound exports the sstable.UserKeyPrefixBound type.
80 : type UserKeyPrefixBound = sstable.UserKeyPrefixBound
81 :
82 : // IterKeyType configures which types of keys an iterator should surface.
83 : type IterKeyType int8
84 :
85 : const (
86 : // IterKeyTypePointsOnly configures an iterator to iterate over point keys
87 : // only.
88 : IterKeyTypePointsOnly IterKeyType = iota
89 : // IterKeyTypeRangesOnly configures an iterator to iterate over range keys
90 : // only.
91 : IterKeyTypeRangesOnly
92 : // IterKeyTypePointsAndRanges configures an iterator iterate over both point
93 : // keys and range keys simultaneously.
94 : IterKeyTypePointsAndRanges
95 : )
96 :
97 : // String implements fmt.Stringer.
98 1 : func (t IterKeyType) String() string {
99 1 : switch t {
100 1 : case IterKeyTypePointsOnly:
101 1 : return "points-only"
102 1 : case IterKeyTypeRangesOnly:
103 1 : return "ranges-only"
104 1 : case IterKeyTypePointsAndRanges:
105 1 : return "points-and-ranges"
106 0 : default:
107 0 : panic(fmt.Sprintf("unknown key type %d", t))
108 : }
109 : }
110 :
111 : // IterOptions hold the optional per-query parameters for NewIter.
112 : //
113 : // Like Options, a nil *IterOptions is valid and means to use the default
114 : // values.
115 : type IterOptions struct {
116 : // LowerBound specifies the smallest key (inclusive) that the iterator will
117 : // return during iteration. If the iterator is seeked or iterated past this
118 : // boundary the iterator will return Valid()==false. Setting LowerBound
119 : // effectively truncates the key space visible to the iterator.
120 : LowerBound []byte
121 : // UpperBound specifies the largest key (exclusive) that the iterator will
122 : // return during iteration. If the iterator is seeked or iterated past this
123 : // boundary the iterator will return Valid()==false. Setting UpperBound
124 : // effectively truncates the key space visible to the iterator.
125 : UpperBound []byte
126 : // SkipPoint may be used to skip over point keys that don't match an
127 : // arbitrary predicate during iteration. If set, the Iterator invokes
128 : // SkipPoint for keys encountered. If SkipPoint returns true, the iterator
129 : // will skip the key without yielding it to the iterator operation in
130 : // progress.
131 : //
132 : // SkipPoint must be a pure function and always return the same result when
133 : // provided the same arguments. The iterator may call SkipPoint multiple
134 : // times for the same user key.
135 : SkipPoint func(userKey []byte) bool
136 : // PointKeyFilters can be used to avoid scanning tables and blocks in tables
137 : // when iterating over point keys. This slice represents an intersection
138 : // across all filters, i.e., all filters must indicate that the block is
139 : // relevant.
140 : //
141 : // Performance note: When len(PointKeyFilters) > 0, the caller should ensure
142 : // that cap(PointKeyFilters) is at least len(PointKeyFilters)+1. This helps
143 : // avoid allocations in Pebble internal code that mutates the slice.
144 : PointKeyFilters []BlockPropertyFilter
145 : // RangeKeyFilters can be usefd to avoid scanning tables and blocks in tables
146 : // when iterating over range keys. The same requirements that apply to
147 : // PointKeyFilters apply here too.
148 : RangeKeyFilters []BlockPropertyFilter
149 : // KeyTypes configures which types of keys to iterate over: point keys,
150 : // range keys, or both.
151 : KeyTypes IterKeyType
152 : // RangeKeyMasking can be used to enable automatic masking of point keys by
153 : // range keys. Range key masking is only supported during combined range key
154 : // and point key iteration mode (IterKeyTypePointsAndRanges).
155 : RangeKeyMasking RangeKeyMasking
156 :
157 : // OnlyReadGuaranteedDurable is an advanced option that is only supported by
158 : // the Reader implemented by DB. When set to true, only the guaranteed to be
159 : // durable state is visible in the iterator.
160 : // - This definition is made under the assumption that the FS implementation
161 : // is providing a durability guarantee when data is synced.
162 : // - The visible state represents a consistent point in the history of the
163 : // DB.
164 : // - The implementation is free to choose a conservative definition of what
165 : // is guaranteed durable. For simplicity, the current implementation
166 : // ignores memtables. A more sophisticated implementation could track the
167 : // highest seqnum that is synced to the WAL and published and use that as
168 : // the visible seqnum for an iterator. Note that the latter approach is
169 : // not strictly better than the former since we can have DBs that are (a)
170 : // synced more rarely than memtable flushes, (b) have no WAL. (a) is
171 : // likely to be true in a future CockroachDB context where the DB
172 : // containing the state machine may be rarely synced.
173 : // NB: this current implementation relies on the fact that memtables are
174 : // flushed in seqnum order, and any ingested sstables that happen to have a
175 : // lower seqnum than a non-flushed memtable don't have any overlapping keys.
176 : // This is the fundamental level invariant used in other code too, like when
177 : // merging iterators.
178 : //
179 : // Semantically, using this option provides the caller a "snapshot" as of
180 : // the time the most recent memtable was flushed. An alternate interface
181 : // would be to add a NewSnapshot variant. Creating a snapshot is heavier
182 : // weight than creating an iterator, so we have opted to support this
183 : // iterator option.
184 : OnlyReadGuaranteedDurable bool
185 : // UseL6Filters allows the caller to opt into reading filter blocks for L6
186 : // sstables. Helpful if a lot of SeekPrefixGEs are expected in quick
187 : // succession, that are also likely to not yield a single key. Filter blocks in
188 : // L6 can be relatively large, often larger than data blocks, so the benefit of
189 : // loading them in the cache is minimized if the probability of the key
190 : // existing is not low or if we just expect a one-time Seek (where loading the
191 : // data block directly is better).
192 : UseL6Filters bool
193 : // Category is used for categorized iterator stats. This should not be
194 : // changed by calling SetOptions.
195 : Category block.Category
196 :
197 : DebugRangeKeyStack bool
198 :
199 : // Internal options.
200 :
201 : logger Logger
202 : // Layer corresponding to this file. Only passed in if constructed by a
203 : // levelIter.
204 : layer manifest.Layer
205 : // disableLazyCombinedIteration is an internal testing option.
206 : disableLazyCombinedIteration bool
207 : // snapshotForHideObsoletePoints is specified for/by levelIter when opening
208 : // files and is used to decide whether to hide obsolete points. A value of 0
209 : // implies obsolete points should not be hidden.
210 : snapshotForHideObsoletePoints base.SeqNum
211 :
212 : // NB: If adding new Options, you must account for them in iterator
213 : // construction and Iterator.SetOptions.
214 : }
215 :
216 : // GetLowerBound returns the LowerBound or nil if the receiver is nil.
217 2 : func (o *IterOptions) GetLowerBound() []byte {
218 2 : if o == nil {
219 2 : return nil
220 2 : }
221 2 : return o.LowerBound
222 : }
223 :
224 : // GetUpperBound returns the UpperBound or nil if the receiver is nil.
225 2 : func (o *IterOptions) GetUpperBound() []byte {
226 2 : if o == nil {
227 2 : return nil
228 2 : }
229 2 : return o.UpperBound
230 : }
231 :
232 2 : func (o *IterOptions) pointKeys() bool {
233 2 : if o == nil {
234 0 : return true
235 0 : }
236 2 : return o.KeyTypes == IterKeyTypePointsOnly || o.KeyTypes == IterKeyTypePointsAndRanges
237 : }
238 :
239 2 : func (o *IterOptions) rangeKeys() bool {
240 2 : if o == nil {
241 0 : return false
242 0 : }
243 2 : return o.KeyTypes == IterKeyTypeRangesOnly || o.KeyTypes == IterKeyTypePointsAndRanges
244 : }
245 :
246 2 : func (o *IterOptions) getLogger() Logger {
247 2 : if o == nil || o.logger == nil {
248 2 : return DefaultLogger
249 2 : }
250 2 : return o.logger
251 : }
252 :
253 : // SpanIterOptions creates a SpanIterOptions from this IterOptions.
254 2 : func (o *IterOptions) SpanIterOptions() keyspan.SpanIterOptions {
255 2 : if o == nil {
256 2 : return keyspan.SpanIterOptions{}
257 2 : }
258 2 : return keyspan.SpanIterOptions{
259 2 : RangeKeyFilters: o.RangeKeyFilters,
260 2 : }
261 : }
262 :
263 : // scanInternalOptions is similar to IterOptions, meant for use with
264 : // scanInternalIterator.
265 : type scanInternalOptions struct {
266 : IterOptions
267 :
268 : category block.Category
269 :
270 : visitPointKey func(key *InternalKey, value LazyValue, iterInfo IteratorLevel) error
271 : visitRangeDel func(start, end []byte, seqNum SeqNum) error
272 : visitRangeKey func(start, end []byte, keys []rangekey.Key) error
273 : visitSharedFile func(sst *SharedSSTMeta) error
274 : visitExternalFile func(sst *ExternalFile) error
275 :
276 : // includeObsoleteKeys specifies whether keys shadowed by newer internal keys
277 : // are exposed. If false, only one internal key per user key is exposed.
278 : includeObsoleteKeys bool
279 :
280 : // rateLimitFunc is used to limit the amount of bytes read per second.
281 : rateLimitFunc func(key *InternalKey, value LazyValue) error
282 : }
283 :
284 : // RangeKeyMasking configures automatic hiding of point keys by range keys. A
285 : // non-nil Suffix enables range-key masking. When enabled, range keys with
286 : // suffixes ≥ Suffix behave as masks. All point keys that are contained within a
287 : // masking range key's bounds and have suffixes greater than the range key's
288 : // suffix are automatically skipped.
289 : //
290 : // Specifically, when configured with a RangeKeyMasking.Suffix _s_, and there
291 : // exists a range key with suffix _r_ covering a point key with suffix _p_, and
292 : //
293 : // _s_ ≤ _r_ < _p_
294 : //
295 : // then the point key is elided.
296 : //
297 : // Range-key masking may only be used when iterating over both point keys and
298 : // range keys with IterKeyTypePointsAndRanges.
299 : type RangeKeyMasking struct {
300 : // Suffix configures which range keys may mask point keys. Only range keys
301 : // that are defined at suffixes greater than or equal to Suffix will mask
302 : // point keys.
303 : Suffix []byte
304 : // Filter is an optional field that may be used to improve performance of
305 : // range-key masking through a block-property filter defined over key
306 : // suffixes. If non-nil, Filter is called by Pebble to construct a
307 : // block-property filter mask at iterator creation. The filter is used to
308 : // skip whole point-key blocks containing point keys with suffixes greater
309 : // than a covering range-key's suffix.
310 : //
311 : // To use this functionality, the caller must create and configure (through
312 : // Options.BlockPropertyCollectors) a block-property collector that records
313 : // the maxmimum suffix contained within a block. The caller then must write
314 : // and provide a BlockPropertyFilterMask implementation on that same
315 : // property. See the BlockPropertyFilterMask type for more information.
316 : Filter func() BlockPropertyFilterMask
317 : }
318 :
319 : // BlockPropertyFilterMask extends the BlockPropertyFilter interface for use
320 : // with range-key masking. Unlike an ordinary block property filter, a
321 : // BlockPropertyFilterMask's filtering criteria is allowed to change when Pebble
322 : // invokes its SetSuffix method.
323 : //
324 : // When a Pebble iterator steps into a range key's bounds and the range key has
325 : // a suffix greater than or equal to RangeKeyMasking.Suffix, the range key acts
326 : // as a mask. The masking range key hides all point keys that fall within the
327 : // range key's bounds and have suffixes > the range key's suffix. Without a
328 : // filter mask configured, Pebble performs this hiding by stepping through point
329 : // keys and comparing suffixes. If large numbers of point keys are masked, this
330 : // requires Pebble to load, iterate through and discard a large number of
331 : // sstable blocks containing masked point keys.
332 : //
333 : // If a block-property collector and a filter mask are configured, Pebble may
334 : // skip loading some point-key blocks altogether. If a block's keys are known to
335 : // all fall within the bounds of the masking range key and the block was
336 : // annotated by a block-property collector with the maximal suffix, Pebble can
337 : // ask the filter mask to compare the property to the current masking range
338 : // key's suffix. If the mask reports no intersection, the block may be skipped.
339 : //
340 : // If unsuffixed and suffixed keys are written to the database, care must be
341 : // taken to avoid unintentionally masking un-suffixed keys located in the same
342 : // block as suffixed keys. One solution is to interpret unsuffixed keys as
343 : // containing the maximal suffix value, ensuring that blocks containing
344 : // unsuffixed keys are always loaded.
345 : type BlockPropertyFilterMask interface {
346 : BlockPropertyFilter
347 :
348 : // SetSuffix configures the mask with the suffix of a range key. The filter
349 : // should return false from Intersects whenever it's provided with a
350 : // property encoding a block's minimum suffix that's greater (according to
351 : // Compare) than the provided suffix.
352 : SetSuffix(suffix []byte) error
353 : }
354 :
355 : // WriteOptions hold the optional per-query parameters for Set and Delete
356 : // operations.
357 : //
358 : // Like Options, a nil *WriteOptions is valid and means to use the default
359 : // values.
360 : type WriteOptions struct {
361 : // Sync is whether to sync writes through the OS buffer cache and down onto
362 : // the actual disk, if applicable. Setting Sync is required for durability of
363 : // individual write operations but can result in slower writes.
364 : //
365 : // If false, and the process or machine crashes, then a recent write may be
366 : // lost. This is due to the recently written data being buffered inside the
367 : // process running Pebble. This differs from the semantics of a write system
368 : // call in which the data is buffered in the OS buffer cache and would thus
369 : // survive a process crash.
370 : //
371 : // The default value is true.
372 : Sync bool
373 : }
374 :
375 : // Sync specifies the default write options for writes which synchronize to
376 : // disk.
377 : var Sync = &WriteOptions{Sync: true}
378 :
379 : // NoSync specifies the default write options for writes which do not
380 : // synchronize to disk.
381 : var NoSync = &WriteOptions{Sync: false}
382 :
383 : // GetSync returns the Sync value or true if the receiver is nil.
384 2 : func (o *WriteOptions) GetSync() bool {
385 2 : return o == nil || o.Sync
386 2 : }
387 :
388 : // LevelOptions holds the optional per-level parameters.
389 : type LevelOptions struct {
390 : // BlockRestartInterval is the number of keys between restart points
391 : // for delta encoding of keys.
392 : //
393 : // The default value is 16.
394 : BlockRestartInterval int
395 :
396 : // BlockSize is the target uncompressed size in bytes of each table block.
397 : //
398 : // The default value is 4096.
399 : BlockSize int
400 :
401 : // BlockSizeThreshold finishes a block if the block size is larger than the
402 : // specified percentage of the target block size and adding the next entry
403 : // would cause the block to be larger than the target block size.
404 : //
405 : // The default value is 90
406 : BlockSizeThreshold int
407 :
408 : // Compression defines the per-block compression to use.
409 : //
410 : // The default value (DefaultCompression) uses snappy compression.
411 : Compression func() Compression
412 :
413 : // FilterPolicy defines a filter algorithm (such as a Bloom filter) that can
414 : // reduce disk reads for Get calls.
415 : //
416 : // One such implementation is bloom.FilterPolicy(10) from the pebble/bloom
417 : // package.
418 : //
419 : // The default value means to use no filter.
420 : FilterPolicy FilterPolicy
421 :
422 : // FilterType defines whether an existing filter policy is applied at a
423 : // block-level or table-level. Block-level filters use less memory to create,
424 : // but are slower to access as a check for the key in the index must first be
425 : // performed to locate the filter block. A table-level filter will require
426 : // memory proportional to the number of keys in an sstable to create, but
427 : // avoids the index lookup when determining if a key is present. Table-level
428 : // filters should be preferred except under constrained memory situations.
429 : FilterType FilterType
430 :
431 : // IndexBlockSize is the target uncompressed size in bytes of each index
432 : // block. When the index block size is larger than this target, two-level
433 : // indexes are automatically enabled. Setting this option to a large value
434 : // (such as math.MaxInt32) disables the automatic creation of two-level
435 : // indexes.
436 : //
437 : // The default value is the value of BlockSize.
438 : IndexBlockSize int
439 :
440 : // The target file size for the level.
441 : TargetFileSize int64
442 : }
443 :
444 : // EnsureDefaults ensures that the default values for all of the options have
445 : // been initialized. It is valid to call EnsureDefaults on a nil receiver. A
446 : // non-nil result will always be returned.
447 2 : func (o *LevelOptions) EnsureDefaults() {
448 2 : if o.BlockRestartInterval <= 0 {
449 1 : o.BlockRestartInterval = base.DefaultBlockRestartInterval
450 1 : }
451 2 : if o.BlockSize <= 0 {
452 1 : o.BlockSize = base.DefaultBlockSize
453 2 : } else if o.BlockSize > sstable.MaximumBlockSize {
454 0 : panic(errors.Errorf("BlockSize %d exceeds MaximumBlockSize", o.BlockSize))
455 : }
456 2 : if o.BlockSizeThreshold <= 0 {
457 1 : o.BlockSizeThreshold = base.DefaultBlockSizeThreshold
458 1 : }
459 2 : if o.Compression == nil {
460 1 : o.Compression = func() Compression { return DefaultCompression }
461 : }
462 2 : if o.IndexBlockSize <= 0 {
463 1 : o.IndexBlockSize = o.BlockSize
464 1 : }
465 2 : if o.TargetFileSize <= 0 {
466 1 : o.TargetFileSize = 2 << 20 // 2 MB
467 1 : }
468 : }
469 :
470 : // Options holds the optional parameters for configuring pebble. These options
471 : // apply to the DB at large; per-query options are defined by the IterOptions
472 : // and WriteOptions types.
473 : type Options struct {
474 : // Sync sstables periodically in order to smooth out writes to disk. This
475 : // option does not provide any persistency guarantee, but is used to avoid
476 : // latency spikes if the OS automatically decides to write out a large chunk
477 : // of dirty filesystem buffers. This option only controls SSTable syncs; WAL
478 : // syncs are controlled by WALBytesPerSync.
479 : //
480 : // The default value is 512KB.
481 : BytesPerSync int
482 :
483 : // Cache is used to cache uncompressed blocks from sstables. If it is nil,
484 : // a block cache of CacheSize will be created for each DB.
485 : Cache *cache.Cache
486 : // CacheSize is used when Cache is not set. The default value is 8 MB.
487 : CacheSize int64
488 :
489 : // LoadBlockSema, if set, is used to limit the number of blocks that can be
490 : // loaded (i.e. read from the filesystem) in parallel. Each load acquires one
491 : // unit from the semaphore for the duration of the read.
492 : LoadBlockSema *fifo.Semaphore
493 :
494 : // Cleaner cleans obsolete files.
495 : //
496 : // The default cleaner uses the DeleteCleaner.
497 : Cleaner Cleaner
498 :
499 : // Local contains option that pertain to files stored on the local filesystem.
500 : Local struct {
501 : // ReadaheadConfig is used to retrieve the current readahead mode; it is
502 : // consulted whenever a read handle is initialized.
503 : ReadaheadConfig *ReadaheadConfig
504 :
505 : // TODO(radu): move BytesPerSync, LoadBlockSema, Cleaner here.
506 : }
507 :
508 : // Comparer defines a total ordering over the space of []byte keys: a 'less
509 : // than' relationship. The same comparison algorithm must be used for reads
510 : // and writes over the lifetime of the DB.
511 : //
512 : // The default value uses the same ordering as bytes.Compare.
513 : Comparer *Comparer
514 :
515 : // DebugCheck is invoked, if non-nil, whenever a new version is being
516 : // installed. Typically, this is set to pebble.DebugCheckLevels in tests
517 : // or tools only, to check invariants over all the data in the database.
518 : DebugCheck func(*DB) error
519 :
520 : // Disable the write-ahead log (WAL). Disabling the write-ahead log prohibits
521 : // crash recovery, but can improve performance if crash recovery is not
522 : // needed (e.g. when only temporary state is being stored in the database).
523 : //
524 : // TODO(peter): untested
525 : DisableWAL bool
526 :
527 : // ErrorIfExists causes an error on Open if the database already exists.
528 : // The error can be checked with errors.Is(err, ErrDBAlreadyExists).
529 : //
530 : // The default value is false.
531 : ErrorIfExists bool
532 :
533 : // ErrorIfNotExists causes an error on Open if the database does not already
534 : // exist. The error can be checked with errors.Is(err, ErrDBDoesNotExist).
535 : //
536 : // The default value is false which will cause a database to be created if it
537 : // does not already exist.
538 : ErrorIfNotExists bool
539 :
540 : // ErrorIfNotPristine causes an error on Open if the database already exists
541 : // and any operations have been performed on the database. The error can be
542 : // checked with errors.Is(err, ErrDBNotPristine).
543 : //
544 : // Note that a database that contained keys that were all subsequently deleted
545 : // may or may not trigger the error. Currently, we check if there are any live
546 : // SSTs or log records to replay.
547 : ErrorIfNotPristine bool
548 :
549 : // EventListener provides hooks to listening to significant DB events such as
550 : // flushes, compactions, and table deletion.
551 : EventListener *EventListener
552 :
553 : // Experimental contains experimental options which are off by default.
554 : // These options are temporary and will eventually either be deleted, moved
555 : // out of the experimental group, or made the non-adjustable default. These
556 : // options may change at any time, so do not rely on them.
557 : Experimental struct {
558 : // The threshold of L0 read-amplification at which compaction concurrency
559 : // is enabled (if CompactionDebtConcurrency was not already exceeded).
560 : // Every multiple of this value enables another concurrent
561 : // compaction up to MaxConcurrentCompactions.
562 : L0CompactionConcurrency int
563 :
564 : // CompactionDebtConcurrency controls the threshold of compaction debt
565 : // at which additional compaction concurrency slots are added. For every
566 : // multiple of this value in compaction debt bytes, an additional
567 : // concurrent compaction is added. This works "on top" of
568 : // L0CompactionConcurrency, so the higher of the count of compaction
569 : // concurrency slots as determined by the two options is chosen.
570 : CompactionDebtConcurrency uint64
571 :
572 : // IngestSplit, if it returns true, allows for ingest-time splitting of
573 : // existing sstables into two virtual sstables to allow ingestion sstables to
574 : // slot into a lower level than they otherwise would have.
575 : IngestSplit func() bool
576 :
577 : // ReadCompactionRate controls the frequency of read triggered
578 : // compactions by adjusting `AllowedSeeks` in manifest.TableMetadata:
579 : //
580 : // AllowedSeeks = FileSize / ReadCompactionRate
581 : //
582 : // From LevelDB:
583 : // ```
584 : // We arrange to automatically compact this file after
585 : // a certain number of seeks. Let's assume:
586 : // (1) One seek costs 10ms
587 : // (2) Writing or reading 1MB costs 10ms (100MB/s)
588 : // (3) A compaction of 1MB does 25MB of IO:
589 : // 1MB read from this level
590 : // 10-12MB read from next level (boundaries may be misaligned)
591 : // 10-12MB written to next level
592 : // This implies that 25 seeks cost the same as the compaction
593 : // of 1MB of data. I.e., one seek costs approximately the
594 : // same as the compaction of 40KB of data. We are a little
595 : // conservative and allow approximately one seek for every 16KB
596 : // of data before triggering a compaction.
597 : // ```
598 : ReadCompactionRate int64
599 :
600 : // ReadSamplingMultiplier is a multiplier for the readSamplingPeriod in
601 : // iterator.maybeSampleRead() to control the frequency of read sampling
602 : // to trigger a read triggered compaction. A value of -1 prevents sampling
603 : // and disables read triggered compactions. The default is 1 << 4. which
604 : // gets multiplied with a constant of 1 << 16 to yield 1 << 20 (1MB).
605 : ReadSamplingMultiplier int64
606 :
607 : // NumDeletionsThreshold defines the minimum number of point tombstones
608 : // that must be present in a single data block for that block to be
609 : // considered tombstone-dense for the purposes of triggering a
610 : // tombstone density compaction. Data blocks may also be considered
611 : // tombstone-dense if they meet the criteria defined by
612 : // DeletionSizeRatioThreshold below. Tombstone-dense blocks are identified
613 : // when sstables are written, and so this is effectively an option for
614 : // sstable writers. The default value is 100.
615 : NumDeletionsThreshold int
616 :
617 : // DeletionSizeRatioThreshold defines the minimum ratio of the size of
618 : // point tombstones to the size of a data block that must be reached
619 : // for that block to be considered tombstone-dense for the purposes of
620 : // triggering a tombstone density compaction. Data blocks may also be
621 : // considered tombstone-dense if they meet the criteria defined by
622 : // NumDeletionsThreshold above. Tombstone-dense blocks are identified
623 : // when sstables are written, and so this is effectively an option for
624 : // sstable writers. The default value is 0.5.
625 : DeletionSizeRatioThreshold float32
626 :
627 : // TombstoneDenseCompactionThreshold is the minimum percent of data
628 : // blocks in a table that must be tombstone-dense for that table to be
629 : // eligible for a tombstone density compaction. It should be defined as a
630 : // ratio out of 1. The default value is 0.10.
631 : //
632 : // If multiple tables are eligible for a tombstone density compaction, then
633 : // tables with a higher percent of tombstone-dense blocks are still
634 : // prioritized for compaction.
635 : //
636 : // A zero or negative value disables tombstone density compactions.
637 : TombstoneDenseCompactionThreshold float64
638 :
639 : // FileCacheShards is the number of shards per file cache.
640 : // Reducing the value can reduce the number of idle goroutines per DB
641 : // instance which can be useful in scenarios with a lot of DB instances
642 : // and a large number of CPUs, but doing so can lead to higher contention
643 : // in the file cache and reduced performance.
644 : //
645 : // The default value is the number of logical CPUs, which can be
646 : // limited by runtime.GOMAXPROCS.
647 : FileCacheShards int
648 :
649 : // ValidateOnIngest schedules validation of sstables after they have
650 : // been ingested.
651 : //
652 : // By default, this value is false.
653 : ValidateOnIngest bool
654 :
655 : // LevelMultiplier configures the size multiplier used to determine the
656 : // desired size of each level of the LSM. Defaults to 10.
657 : LevelMultiplier int
658 :
659 : // MultiLevelCompactionHeuristic determines whether to add an additional
660 : // level to a conventional two level compaction. If nil, a multilevel
661 : // compaction will never get triggered.
662 : MultiLevelCompactionHeuristic MultiLevelHeuristic
663 :
664 : // EnableColumnarBlocks is used to decide whether to enable writing
665 : // TableFormatPebblev5 sstables. This setting is only respected by
666 : // FormatColumnarBlocks. In lower format major versions, the
667 : // TableFormatPebblev5 format is prohibited. If EnableColumnarBlocks is
668 : // nil and the DB is at FormatColumnarBlocks, the DB defaults to not
669 : // writing columnar blocks.
670 : EnableColumnarBlocks func() bool
671 :
672 : // EnableValueBlocks is used to decide whether to enable writing
673 : // TableFormatPebblev3 sstables. This setting is only respected by a
674 : // specific subset of format major versions: FormatSSTableValueBlocks,
675 : // FormatFlushableIngest and FormatPrePebblev1MarkedCompacted. In lower
676 : // format major versions, value blocks are never enabled. In higher
677 : // format major versions, value blocks are always enabled.
678 : EnableValueBlocks func() bool
679 :
680 : // ShortAttributeExtractor is used iff EnableValueBlocks() returns true
681 : // (else ignored). If non-nil, a ShortAttribute can be extracted from the
682 : // value and stored with the key, when the value is stored elsewhere.
683 : ShortAttributeExtractor ShortAttributeExtractor
684 :
685 : // RequiredInPlaceValueBound specifies an optional span of user key
686 : // prefixes that are not-MVCC, but have a suffix. For these the values
687 : // must be stored with the key, since the concept of "older versions" is
688 : // not defined. It is also useful for statically known exclusions to value
689 : // separation. In CockroachDB, this will be used for the lock table key
690 : // space that has non-empty suffixes, but those locks don't represent
691 : // actual MVCC versions (the suffix ordering is arbitrary). We will also
692 : // need to add support for dynamically configured exclusions (we want the
693 : // default to be to allow Pebble to decide whether to separate the value
694 : // or not, hence this is structured as exclusions), for example, for users
695 : // of CockroachDB to dynamically exclude certain tables.
696 : //
697 : // Any change in exclusion behavior takes effect only on future written
698 : // sstables, and does not start rewriting existing sstables.
699 : //
700 : // Even ignoring changes in this setting, exclusions are interpreted as a
701 : // guidance by Pebble, and not necessarily honored. Specifically, user
702 : // keys with multiple Pebble-versions *may* have the older versions stored
703 : // in value blocks.
704 : RequiredInPlaceValueBound UserKeyPrefixBound
705 :
706 : // DisableIngestAsFlushable disables lazy ingestion of sstables through
707 : // a WAL write and memtable rotation. Only effectual if the format
708 : // major version is at least `FormatFlushableIngest`.
709 : DisableIngestAsFlushable func() bool
710 :
711 : // RemoteStorage enables use of remote storage (e.g. S3) for storing
712 : // sstables. Setting this option enables use of CreateOnShared option and
713 : // allows ingestion of external files.
714 : RemoteStorage remote.StorageFactory
715 :
716 : // If CreateOnShared is non-zero, new sstables are created on remote storage
717 : // (using CreateOnSharedLocator and with the appropriate
718 : // CreateOnSharedStrategy). These sstables can be shared between different
719 : // Pebble instances; the lifecycle of such objects is managed by the
720 : // remote.Storage constructed by options.RemoteStorage.
721 : //
722 : // Can only be used when RemoteStorage is set (and recognizes
723 : // CreateOnSharedLocator).
724 : CreateOnShared remote.CreateOnSharedStrategy
725 : CreateOnSharedLocator remote.Locator
726 :
727 : // CacheSizeBytesBytes is the size of the on-disk block cache for objects
728 : // on shared storage in bytes. If it is 0, no cache is used.
729 : SecondaryCacheSizeBytes int64
730 :
731 : // EnableDeleteOnlyCompactionExcises enables delete-only compactions to also
732 : // apply delete-only compaction hints on sstables that partially overlap
733 : // with it. This application happens through an excise, similar to
734 : // the excise phase of IngestAndExcise.
735 : EnableDeleteOnlyCompactionExcises func() bool
736 :
737 : // CompactionScheduler, if set, is used to limit concurrent compactions as
738 : // well as to pace compactions already chosen. If nil, a default scheduler
739 : // is created and used.
740 : CompactionScheduler CompactionScheduler
741 :
742 : UserKeyCategories UserKeyCategories
743 : }
744 :
745 : // Filters is a map from filter policy name to filter policy. It is used for
746 : // debugging tools which may be used on multiple databases configured with
747 : // different filter policies. It is not necessary to populate this filters
748 : // map during normal usage of a DB (it will be done automatically by
749 : // EnsureDefaults).
750 : Filters map[string]FilterPolicy
751 :
752 : // FlushDelayDeleteRange configures how long the database should wait before
753 : // forcing a flush of a memtable that contains a range deletion. Disk space
754 : // cannot be reclaimed until the range deletion is flushed. No automatic
755 : // flush occurs if zero.
756 : FlushDelayDeleteRange time.Duration
757 :
758 : // FlushDelayRangeKey configures how long the database should wait before
759 : // forcing a flush of a memtable that contains a range key. Range keys in
760 : // the memtable prevent lazy combined iteration, so it's desirable to flush
761 : // range keys promptly. No automatic flush occurs if zero.
762 : FlushDelayRangeKey time.Duration
763 :
764 : // FlushSplitBytes denotes the target number of bytes per sublevel in
765 : // each flush split interval (i.e. range between two flush split keys)
766 : // in L0 sstables. When set to zero, only a single sstable is generated
767 : // by each flush. When set to a non-zero value, flushes are split at
768 : // points to meet L0's TargetFileSize, any grandparent-related overlap
769 : // options, and at boundary keys of L0 flush split intervals (which are
770 : // targeted to contain around FlushSplitBytes bytes in each sublevel
771 : // between pairs of boundary keys). Splitting sstables during flush
772 : // allows increased compaction flexibility and concurrency when those
773 : // tables are compacted to lower levels.
774 : FlushSplitBytes int64
775 :
776 : // FormatMajorVersion sets the format of on-disk files. It is
777 : // recommended to set the format major version to an explicit
778 : // version, as the default may change over time.
779 : //
780 : // At Open if the existing database is formatted using a later
781 : // format major version that is known to this version of Pebble,
782 : // Pebble will continue to use the later format major version. If
783 : // the existing database's version is unknown, the caller may use
784 : // FormatMostCompatible and will be able to open the database
785 : // regardless of its actual version.
786 : //
787 : // If the existing database is formatted using a format major
788 : // version earlier than the one specified, Open will automatically
789 : // ratchet the database to the specified format major version.
790 : FormatMajorVersion FormatMajorVersion
791 :
792 : // FS provides the interface for persistent file storage.
793 : //
794 : // The default value uses the underlying operating system's file system.
795 : FS vfs.FS
796 :
797 : // KeySchema is the name of the key schema that should be used when writing
798 : // new sstables. There must be a key schema with this name defined in
799 : // KeySchemas. If not set, colblk.DefaultKeySchema is used to construct a
800 : // default key schema.
801 : KeySchema string
802 :
803 : // KeySchemas defines the set of known schemas of user keys. When columnar
804 : // blocks are in use (see FormatColumnarBlocks), the user may specify how a
805 : // key should be decomposed into columns. Each KeySchema must have a unique
806 : // name. The schema named by Options.KeySchema is used while writing
807 : // sstables during flushes and compactions.
808 : //
809 : // Multiple KeySchemas may be used over the lifetime of a database. Once a
810 : // KeySchema is used, it must be provided in KeySchemas in subsequent calls
811 : // to Open for perpetuity.
812 : KeySchemas sstable.KeySchemas
813 :
814 : // Lock, if set, must be a database lock acquired through LockDirectory for
815 : // the same directory passed to Open. If provided, Open will skip locking
816 : // the directory. Closing the database will not release the lock, and it's
817 : // the responsibility of the caller to release the lock after closing the
818 : // database.
819 : //
820 : // Open will enforce that the Lock passed locks the same directory passed to
821 : // Open. Concurrent calls to Open using the same Lock are detected and
822 : // prohibited.
823 : Lock *Lock
824 :
825 : // The count of L0 files necessary to trigger an L0 compaction.
826 : L0CompactionFileThreshold int
827 :
828 : // The amount of L0 read-amplification necessary to trigger an L0 compaction.
829 : L0CompactionThreshold int
830 :
831 : // Hard limit on L0 read-amplification, computed as the number of L0
832 : // sublevels. Writes are stopped when this threshold is reached.
833 : L0StopWritesThreshold int
834 :
835 : // The maximum number of bytes for LBase. The base level is the level which
836 : // L0 is compacted into. The base level is determined dynamically based on
837 : // the existing data in the LSM. The maximum number of bytes for other levels
838 : // is computed dynamically based on the base level's maximum size. When the
839 : // maximum number of bytes for a level is exceeded, compaction is requested.
840 : LBaseMaxBytes int64
841 :
842 : // Per-level options. Options for at least one level must be specified. The
843 : // options for the last level are used for all subsequent levels.
844 : Levels []LevelOptions
845 :
846 : // LoggerAndTracer will be used, if non-nil, else Logger will be used and
847 : // tracing will be a noop.
848 :
849 : // Logger used to write log messages.
850 : //
851 : // The default logger uses the Go standard library log package.
852 : Logger Logger
853 : // LoggerAndTracer is used for writing log messages and traces.
854 : LoggerAndTracer LoggerAndTracer
855 :
856 : // MaxManifestFileSize is the maximum size the MANIFEST file is allowed to
857 : // become. When the MANIFEST exceeds this size it is rolled over and a new
858 : // MANIFEST is created.
859 : MaxManifestFileSize int64
860 :
861 : // MaxOpenFiles is a soft limit on the number of open files that can be
862 : // used by the DB.
863 : //
864 : // The default value is 1000.
865 : MaxOpenFiles int
866 :
867 : // The size of a MemTable in steady state. The actual MemTable size starts at
868 : // min(256KB, MemTableSize) and doubles for each subsequent MemTable up to
869 : // MemTableSize. This reduces the memory pressure caused by MemTables for
870 : // short lived (test) DB instances. Note that more than one MemTable can be
871 : // in existence since flushing a MemTable involves creating a new one and
872 : // writing the contents of the old one in the
873 : // background. MemTableStopWritesThreshold places a hard limit on the size of
874 : // the queued MemTables.
875 : //
876 : // The default value is 4MB.
877 : MemTableSize uint64
878 :
879 : // Hard limit on the number of queued of MemTables. Writes are stopped when
880 : // the sum of the queued memtable sizes exceeds:
881 : // MemTableStopWritesThreshold * MemTableSize.
882 : //
883 : // This value should be at least 2 or writes will stop whenever a MemTable is
884 : // being flushed.
885 : //
886 : // The default value is 2.
887 : MemTableStopWritesThreshold int
888 :
889 : // Merger defines the associative merge operation to use for merging values
890 : // written with {Batch,DB}.Merge.
891 : //
892 : // The default merger concatenates values.
893 : Merger *Merger
894 :
895 : // MaxConcurrentCompactions is the upper bound on the value returned by
896 : // DB.GetAllowedWithoutPermission (reported to the CompactionScheduler).
897 : // More abstractly, it is a rough upper bound on the number of concurrent
898 : // compactions, not including download compactions (which have a separate
899 : // limit specified by MaxConcurrentDownloads).
900 : //
901 : // This is a rough upper bound since delete-only compactions (a) do not use
902 : // the CompactionScheduler, and (b) the CompactionScheduler may use other
903 : // criteria to decide on how many compactions to permit.
904 : //
905 : // Elaborating on (b), when the ConcurrencyLimitScheduler is being used, the
906 : // value returned by DB.GetAllowedWithoutPermission fully controls how many
907 : // compactions get to run. Other CompactionSchedulers may use additional
908 : // criteria, like resource availability.
909 : //
910 : // Elaborating on (a), we don't use the CompactionScheduler to schedule
911 : // delete-only compactions since they are expected to be almost free from a
912 : // CPU and disk usage perspective. Since the CompactionScheduler does not
913 : // know about their existence, the total running count can exceed this
914 : // value. For example, consider MaxConcurrentCompactions returns 3, and the
915 : // current value returned from DB.GetAllowedWithoutPermission is also 3. Say
916 : // 3 delete-only compactions are also running. Then the
917 : // ConcurrencyLimitScheduler can also start 3 other compactions, for a total
918 : // of 6.
919 : //
920 : // DB.GetAllowedWithoutPermission returns a value in the interval [1,
921 : // MaxConcurrentCompactions]. A value > 1 is returned:
922 : // - when L0 read-amplification passes the L0CompactionConcurrency threshold;
923 : // - when compaction debt passes the CompactionDebtConcurrency threshold;
924 : // - when there are multiple manual compactions waiting to run.
925 : //
926 : // MaxConcurrentCompactions() must be greater than 0.
927 : //
928 : // The default value is 1.
929 : MaxConcurrentCompactions func() int
930 :
931 : // MaxConcurrentDownloads specifies the maximum number of download
932 : // compactions. These are compactions that copy an external file to the local
933 : // store.
934 : //
935 : // This limit is independent of MaxConcurrentCompactions; at any point in
936 : // time, we may be running MaxConcurrentCompactions non-download compactions
937 : // and MaxConcurrentDownloads download compactions.
938 : //
939 : // MaxConcurrentDownloads() must be greater than 0.
940 : //
941 : // The default value is 1.
942 : MaxConcurrentDownloads func() int
943 :
944 : // DisableAutomaticCompactions dictates whether automatic compactions are
945 : // scheduled or not. The default is false (enabled). This option is only used
946 : // externally when running a manual compaction, and internally for tests.
947 : DisableAutomaticCompactions bool
948 :
949 : // DisableConsistencyCheck disables the consistency check that is performed on
950 : // open. Should only be used when a database cannot be opened normally (e.g.
951 : // some of the tables don't exist / aren't accessible).
952 : DisableConsistencyCheck bool
953 :
954 : // DisableTableStats dictates whether tables should be loaded asynchronously
955 : // to compute statistics that inform compaction heuristics. The collection
956 : // of table stats improves compaction of tombstones, reclaiming disk space
957 : // more quickly and in some cases reducing write amplification in the
958 : // presence of tombstones. Disabling table stats may be useful in tests
959 : // that require determinism as the asynchronicity of table stats collection
960 : // introduces significant nondeterminism.
961 : DisableTableStats bool
962 :
963 : // NoSyncOnClose decides whether the Pebble instance will enforce a
964 : // close-time synchronization (e.g., fdatasync() or sync_file_range())
965 : // on files it writes to. Setting this to true removes the guarantee for a
966 : // sync on close. Some implementations can still issue a non-blocking sync.
967 : NoSyncOnClose bool
968 :
969 : // NumPrevManifest is the number of non-current or older manifests which
970 : // we want to keep around for debugging purposes. By default, we're going
971 : // to keep one older manifest.
972 : NumPrevManifest int
973 :
974 : // ReadOnly indicates that the DB should be opened in read-only mode. Writes
975 : // to the DB will return an error, background compactions are disabled, and
976 : // the flush that normally occurs after replaying the WAL at startup is
977 : // disabled.
978 : ReadOnly bool
979 :
980 : // FileCache is an initialized FileCache which should be set as an
981 : // option if the DB needs to be initialized with a pre-existing file cache.
982 : // If FileCache is nil, then a file cache which is unique to the DB instance
983 : // is created. FileCache can be shared between db instances by setting it here.
984 : // The FileCache set here must use the same underlying cache as Options.Cache
985 : // and pebble will panic otherwise.
986 : FileCache *FileCache
987 :
988 : // BlockPropertyCollectors is a list of BlockPropertyCollector creation
989 : // functions. A new BlockPropertyCollector is created for each sstable
990 : // built and lives for the lifetime of writing that table.
991 : BlockPropertyCollectors []func() BlockPropertyCollector
992 :
993 : // WALBytesPerSync sets the number of bytes to write to a WAL before calling
994 : // Sync on it in the background. Just like with BytesPerSync above, this
995 : // helps smooth out disk write latencies, and avoids cases where the OS
996 : // writes a lot of buffered data to disk at once. However, this is less
997 : // necessary with WALs, as many write operations already pass in
998 : // Sync = true.
999 : //
1000 : // The default value is 0, i.e. no background syncing. This matches the
1001 : // default behaviour in RocksDB.
1002 : WALBytesPerSync int
1003 :
1004 : // WALDir specifies the directory to store write-ahead logs (WALs) in. If
1005 : // empty (the default), WALs will be stored in the same directory as sstables
1006 : // (i.e. the directory passed to pebble.Open).
1007 : WALDir string
1008 :
1009 : // WALFailover may be set to configure Pebble to monitor writes to its
1010 : // write-ahead log and failover to writing write-ahead log entries to a
1011 : // secondary location (eg, a separate physical disk). WALFailover may be
1012 : // used to improve write availability in the presence of transient disk
1013 : // unavailability.
1014 : WALFailover *WALFailoverOptions
1015 :
1016 : // WALRecoveryDirs is a list of additional directories that should be
1017 : // scanned for the existence of additional write-ahead logs. WALRecoveryDirs
1018 : // is expected to be used when starting Pebble with a new WALDir or a new
1019 : // WALFailover configuration. The directories associated with the previous
1020 : // configuration may still contain WALs that are required for recovery of
1021 : // the current database state.
1022 : //
1023 : // If a previous WAL configuration may have stored WALs elsewhere but there
1024 : // is not a corresponding entry in WALRecoveryDirs, Open will error.
1025 : WALRecoveryDirs []wal.Dir
1026 :
1027 : // WALMinSyncInterval is the minimum duration between syncs of the WAL. If
1028 : // WAL syncs are requested faster than this interval, they will be
1029 : // artificially delayed. Introducing a small artificial delay (500us) between
1030 : // WAL syncs can allow more operations to arrive and reduce IO operations
1031 : // while having a minimal impact on throughput. This option is supplied as a
1032 : // closure in order to allow the value to be changed dynamically. The default
1033 : // value is 0.
1034 : //
1035 : // TODO(peter): rather than a closure, should there be another mechanism for
1036 : // changing options dynamically?
1037 : WALMinSyncInterval func() time.Duration
1038 :
1039 : // The controls below manage deletion pacing, which slows down
1040 : // deletions when compactions finish or when readers close and
1041 : // obsolete files must be cleaned up. Rapid deletion of many
1042 : // files simultaneously can increase disk latency on certain
1043 : // SSDs, and this functionality helps protect against that.
1044 :
1045 : // TargetByteDeletionRate is the rate (in bytes per second) at which sstable file
1046 : // deletions are limited to (under normal circumstances).
1047 : //
1048 : // This value is only a best-effort target; the effective rate can be
1049 : // higher if deletions are falling behind or disk space is running low.
1050 : //
1051 : // Setting this to 0 disables deletion pacing, which is also the default.
1052 : TargetByteDeletionRate int
1053 :
1054 : // FreeSpaceThresholdBytes specifies the minimum amount of free disk space that Pebble
1055 : // attempts to maintain. If free disk space drops below this threshold, deletions
1056 : // are accelerated above TargetByteDeletionRate until the threshold is restored.
1057 : // Default is 16GB.
1058 : FreeSpaceThresholdBytes uint64
1059 :
1060 : // FreeSpaceTimeframe sets the duration (in seconds) within which Pebble attempts
1061 : // to restore the free disk space back to FreeSpaceThreshold. A lower value means
1062 : // more aggressive deletions. Default is 10s.
1063 : FreeSpaceTimeframe time.Duration
1064 :
1065 : // ObsoleteBytesMaxRatio specifies the maximum allowed ratio of obsolete files to
1066 : // live files. If this ratio is exceeded, Pebble speeds up deletions above the
1067 : // TargetByteDeletionRate until the ratio is restored. Default is 0.20.
1068 : ObsoleteBytesMaxRatio float64
1069 :
1070 : // ObsoleteBytesTimeframe sets the duration (in seconds) within which Pebble aims
1071 : // to restore the obsolete-to-live bytes ratio below ObsoleteBytesMaxRatio. A lower
1072 : // value means more aggressive deletions. Default is 300s.
1073 : ObsoleteBytesTimeframe time.Duration
1074 :
1075 : // EnableSQLRowSpillMetrics specifies whether the Pebble instance will only be used
1076 : // to temporarily persist data spilled to disk for row-oriented SQL query execution.
1077 : EnableSQLRowSpillMetrics bool
1078 :
1079 : // AllocatorSizeClasses provides a sorted list containing the supported size
1080 : // classes of the underlying memory allocator. This provides hints to the
1081 : // sstable block writer's flushing policy to select block sizes that
1082 : // preemptively reduce internal fragmentation when loaded into the block cache.
1083 : AllocatorSizeClasses []int
1084 :
1085 : // private options are only used by internal tests or are used internally
1086 : // for facilitating upgrade paths of unconfigurable functionality.
1087 : private struct {
1088 : // disableDeleteOnlyCompactions prevents the scheduling of delete-only
1089 : // compactions that drop sstables wholy covered by range tombstones or
1090 : // range key tombstones.
1091 : disableDeleteOnlyCompactions bool
1092 :
1093 : // disableElisionOnlyCompactions prevents the scheduling of elision-only
1094 : // compactions that rewrite sstables in place in order to elide obsolete
1095 : // keys.
1096 : disableElisionOnlyCompactions bool
1097 :
1098 : // disableLazyCombinedIteration is a private option used by the
1099 : // metamorphic tests to test equivalence between lazy-combined iteration
1100 : // and constructing the range-key iterator upfront. It's a private
1101 : // option to avoid littering the public interface with options that we
1102 : // do not want to allow users to actually configure.
1103 : disableLazyCombinedIteration bool
1104 :
1105 : // testingAlwaysWaitForCleanup is set by some tests to force waiting for
1106 : // obsolete file deletion (to make events deterministic).
1107 : testingAlwaysWaitForCleanup bool
1108 :
1109 : // fsCloser holds a closer that should be invoked after a DB using these
1110 : // Options is closed. This is used to automatically stop the
1111 : // long-running goroutine associated with the disk-health-checking FS.
1112 : // See the initialization of FS in EnsureDefaults. Note that care has
1113 : // been taken to ensure that it is still safe to continue using the FS
1114 : // after this closer has been invoked. However, if write operations
1115 : // against the FS are made after the DB is closed, the FS may leak a
1116 : // goroutine indefinitely.
1117 : fsCloser io.Closer
1118 : }
1119 : }
1120 :
1121 : // WALFailoverOptions configures the WAL failover mechanics to use during
1122 : // transient write unavailability on the primary WAL volume.
1123 : type WALFailoverOptions struct {
1124 : // Secondary indicates the secondary directory and VFS to use in the event a
1125 : // write to the primary WAL stalls.
1126 : Secondary wal.Dir
1127 : // FailoverOptions provides configuration of the thresholds and intervals
1128 : // involved in WAL failover. If any of its fields are left unspecified,
1129 : // reasonable defaults will be used.
1130 : wal.FailoverOptions
1131 : }
1132 :
1133 : // ReadaheadConfig controls the use of read-ahead.
1134 : type ReadaheadConfig = objstorageprovider.ReadaheadConfig
1135 :
1136 : // JemallocSizeClasses exports sstable.JemallocSizeClasses.
1137 : var JemallocSizeClasses = sstable.JemallocSizeClasses
1138 :
1139 : // DebugCheckLevels calls CheckLevels on the provided database.
1140 : // It may be set in the DebugCheck field of Options to check
1141 : // level invariants whenever a new version is installed.
1142 2 : func DebugCheckLevels(db *DB) error {
1143 2 : return db.CheckLevels(nil)
1144 2 : }
1145 :
1146 : // EnsureDefaults ensures that the default values for all options are set if a
1147 : // valid value was not already specified.
1148 2 : func (o *Options) EnsureDefaults() {
1149 2 : if o.Cache == nil && o.CacheSize == 0 {
1150 1 : o.CacheSize = cacheDefaultSize
1151 1 : }
1152 2 : o.Comparer = o.Comparer.EnsureDefaults()
1153 2 :
1154 2 : if o.BytesPerSync <= 0 {
1155 1 : o.BytesPerSync = 512 << 10 // 512 KB
1156 1 : }
1157 2 : if o.Cleaner == nil {
1158 1 : o.Cleaner = DeleteCleaner{}
1159 1 : }
1160 :
1161 2 : if o.FreeSpaceThresholdBytes == 0 {
1162 1 : o.FreeSpaceThresholdBytes = 16 << 30 // 16 GB
1163 1 : }
1164 :
1165 2 : if o.FreeSpaceTimeframe == 0 {
1166 1 : o.FreeSpaceTimeframe = 10 * time.Second
1167 1 : }
1168 :
1169 2 : if o.ObsoleteBytesMaxRatio == 0 {
1170 1 : o.ObsoleteBytesMaxRatio = 0.20
1171 1 : }
1172 :
1173 2 : if o.ObsoleteBytesTimeframe == 0 {
1174 1 : o.ObsoleteBytesTimeframe = 300 * time.Second
1175 1 : }
1176 :
1177 2 : if o.Experimental.DisableIngestAsFlushable == nil {
1178 2 : o.Experimental.DisableIngestAsFlushable = func() bool { return false }
1179 : }
1180 2 : if o.Experimental.L0CompactionConcurrency <= 0 {
1181 1 : o.Experimental.L0CompactionConcurrency = 10
1182 1 : }
1183 2 : if o.Experimental.CompactionDebtConcurrency <= 0 {
1184 1 : o.Experimental.CompactionDebtConcurrency = 1 << 30 // 1 GB
1185 1 : }
1186 2 : if o.KeySchema == "" && len(o.KeySchemas) == 0 {
1187 1 : ks := colblk.DefaultKeySchema(o.Comparer, 16 /* bundleSize */)
1188 1 : o.KeySchema = ks.Name
1189 1 : o.KeySchemas = sstable.MakeKeySchemas(&ks)
1190 1 : }
1191 2 : if o.L0CompactionThreshold <= 0 {
1192 1 : o.L0CompactionThreshold = 4
1193 1 : }
1194 2 : if o.L0CompactionFileThreshold <= 0 {
1195 1 : // Some justification for the default of 500:
1196 1 : // Why not smaller?:
1197 1 : // - The default target file size for L0 is 2MB, so 500 files is <= 1GB
1198 1 : // of data. At observed compaction speeds of > 20MB/s, L0 can be
1199 1 : // cleared of all files in < 1min, so this backlog is not huge.
1200 1 : // - 500 files is low overhead for instantiating L0 sublevels from
1201 1 : // scratch.
1202 1 : // - Lower values were observed to cause excessive and inefficient
1203 1 : // compactions out of L0 in a TPCC import benchmark.
1204 1 : // Why not larger?:
1205 1 : // - More than 1min to compact everything out of L0.
1206 1 : // - CockroachDB's admission control system uses a threshold of 1000
1207 1 : // files to start throttling writes to Pebble. Using 500 here gives
1208 1 : // us headroom between when Pebble should start compacting L0 and
1209 1 : // when the admission control threshold is reached.
1210 1 : //
1211 1 : // We can revisit this default in the future based on better
1212 1 : // experimental understanding.
1213 1 : //
1214 1 : // TODO(jackson): Experiment with slightly lower thresholds [or higher
1215 1 : // admission control thresholds] to see whether a higher L0 score at the
1216 1 : // threshold (currently 2.0) is necessary for some workloads to avoid
1217 1 : // starving L0 in favor of lower-level compactions.
1218 1 : o.L0CompactionFileThreshold = 500
1219 1 : }
1220 2 : if o.L0StopWritesThreshold <= 0 {
1221 1 : o.L0StopWritesThreshold = 12
1222 1 : }
1223 2 : if o.LBaseMaxBytes <= 0 {
1224 1 : o.LBaseMaxBytes = 64 << 20 // 64 MB
1225 1 : }
1226 2 : if o.Levels == nil {
1227 1 : o.Levels = make([]LevelOptions, 1)
1228 1 : for i := range o.Levels {
1229 1 : if i > 0 {
1230 0 : l := &o.Levels[i]
1231 0 : if l.TargetFileSize <= 0 {
1232 0 : l.TargetFileSize = o.Levels[i-1].TargetFileSize * 2
1233 0 : }
1234 : }
1235 1 : o.Levels[i].EnsureDefaults()
1236 : }
1237 2 : } else {
1238 2 : for i := range o.Levels {
1239 2 : o.Levels[i].EnsureDefaults()
1240 2 : }
1241 : }
1242 2 : if o.Logger == nil {
1243 2 : o.Logger = DefaultLogger
1244 2 : }
1245 2 : if o.EventListener == nil {
1246 2 : o.EventListener = &EventListener{}
1247 2 : }
1248 2 : o.EventListener.EnsureDefaults(o.Logger)
1249 2 : if o.MaxManifestFileSize == 0 {
1250 1 : o.MaxManifestFileSize = 128 << 20 // 128 MB
1251 1 : }
1252 2 : if o.MaxOpenFiles == 0 {
1253 1 : o.MaxOpenFiles = 1000
1254 1 : }
1255 2 : if o.MemTableSize <= 0 {
1256 1 : o.MemTableSize = 4 << 20 // 4 MB
1257 1 : }
1258 2 : if o.MemTableStopWritesThreshold <= 0 {
1259 1 : o.MemTableStopWritesThreshold = 2
1260 1 : }
1261 2 : if o.Merger == nil {
1262 1 : o.Merger = DefaultMerger
1263 1 : }
1264 2 : if o.MaxConcurrentCompactions == nil {
1265 1 : o.MaxConcurrentCompactions = func() int { return 1 }
1266 : }
1267 2 : if o.MaxConcurrentDownloads == nil {
1268 1 : o.MaxConcurrentDownloads = func() int { return 1 }
1269 : }
1270 2 : if o.NumPrevManifest <= 0 {
1271 2 : o.NumPrevManifest = 1
1272 2 : }
1273 :
1274 2 : if o.FormatMajorVersion == FormatDefault {
1275 1 : o.FormatMajorVersion = FormatMinSupported
1276 1 : if o.Experimental.CreateOnShared != remote.CreateOnSharedNone {
1277 1 : o.FormatMajorVersion = FormatMinForSharedObjects
1278 1 : }
1279 : }
1280 :
1281 2 : if o.FS == nil {
1282 1 : o.WithFSDefaults()
1283 1 : }
1284 2 : if o.FlushSplitBytes <= 0 {
1285 1 : o.FlushSplitBytes = 2 * o.Levels[0].TargetFileSize
1286 1 : }
1287 2 : if o.WALFailover != nil {
1288 2 : o.WALFailover.FailoverOptions.EnsureDefaults()
1289 2 : }
1290 2 : if o.Experimental.LevelMultiplier <= 0 {
1291 2 : o.Experimental.LevelMultiplier = defaultLevelMultiplier
1292 2 : }
1293 2 : if o.Experimental.ReadCompactionRate == 0 {
1294 1 : o.Experimental.ReadCompactionRate = 16000
1295 1 : }
1296 2 : if o.Experimental.ReadSamplingMultiplier == 0 {
1297 1 : o.Experimental.ReadSamplingMultiplier = 1 << 4
1298 1 : }
1299 2 : if o.Experimental.NumDeletionsThreshold == 0 {
1300 1 : o.Experimental.NumDeletionsThreshold = sstable.DefaultNumDeletionsThreshold
1301 1 : }
1302 2 : if o.Experimental.DeletionSizeRatioThreshold == 0 {
1303 1 : o.Experimental.DeletionSizeRatioThreshold = sstable.DefaultDeletionSizeRatioThreshold
1304 1 : }
1305 2 : if o.Experimental.TombstoneDenseCompactionThreshold == 0 {
1306 1 : o.Experimental.TombstoneDenseCompactionThreshold = 0.10
1307 1 : }
1308 2 : if o.Experimental.FileCacheShards <= 0 {
1309 1 : o.Experimental.FileCacheShards = runtime.GOMAXPROCS(0)
1310 1 : }
1311 2 : if o.Experimental.MultiLevelCompactionHeuristic == nil {
1312 1 : o.Experimental.MultiLevelCompactionHeuristic = WriteAmpHeuristic{}
1313 1 : }
1314 :
1315 2 : o.initMaps()
1316 : }
1317 :
1318 : // DefaultOptions returns a new Options object with the default values set.
1319 1 : func DefaultOptions() *Options {
1320 1 : o := &Options{}
1321 1 : o.EnsureDefaults()
1322 1 : return o
1323 1 : }
1324 :
1325 : // WithFSDefaults configures the Options to wrap the configured filesystem with
1326 : // the default virtual file system middleware, like disk-health checking.
1327 2 : func (o *Options) WithFSDefaults() {
1328 2 : if o.FS == nil {
1329 1 : o.FS = vfs.Default
1330 1 : }
1331 2 : o.FS, o.private.fsCloser = vfs.WithDiskHealthChecks(o.FS, 5*time.Second, nil,
1332 2 : func(info vfs.DiskSlowInfo) {
1333 0 : o.EventListener.DiskSlow(info)
1334 0 : })
1335 : }
1336 :
1337 : // AddEventListener adds the provided event listener to the Options, in addition
1338 : // to any existing event listener.
1339 1 : func (o *Options) AddEventListener(l EventListener) {
1340 1 : if o.EventListener != nil {
1341 1 : l = TeeEventListener(l, *o.EventListener)
1342 1 : }
1343 1 : o.EventListener = &l
1344 : }
1345 :
1346 : // initMaps initializes the Comparers, Filters, and Mergers maps.
1347 2 : func (o *Options) initMaps() {
1348 2 : for i := range o.Levels {
1349 2 : l := &o.Levels[i]
1350 2 : if l.FilterPolicy != nil {
1351 2 : if o.Filters == nil {
1352 2 : o.Filters = make(map[string]FilterPolicy)
1353 2 : }
1354 2 : name := l.FilterPolicy.Name()
1355 2 : if _, ok := o.Filters[name]; !ok {
1356 2 : o.Filters[name] = l.FilterPolicy
1357 2 : }
1358 : }
1359 : }
1360 : }
1361 :
1362 : // Level returns the LevelOptions for the specified level.
1363 2 : func (o *Options) Level(level int) LevelOptions {
1364 2 : if level < len(o.Levels) {
1365 2 : return o.Levels[level]
1366 2 : }
1367 2 : n := len(o.Levels) - 1
1368 2 : l := o.Levels[n]
1369 2 : for i := n; i < level; i++ {
1370 2 : l.TargetFileSize *= 2
1371 2 : }
1372 2 : return l
1373 : }
1374 :
1375 : // Clone creates a shallow-copy of the supplied options.
1376 2 : func (o *Options) Clone() *Options {
1377 2 : n := &Options{}
1378 2 : if o != nil {
1379 2 : *n = *o
1380 2 : }
1381 2 : return n
1382 : }
1383 :
1384 2 : func filterPolicyName(p FilterPolicy) string {
1385 2 : if p == nil {
1386 2 : return "none"
1387 2 : }
1388 2 : return p.Name()
1389 : }
1390 :
1391 2 : func (o *Options) String() string {
1392 2 : var buf bytes.Buffer
1393 2 :
1394 2 : cacheSize := o.CacheSize
1395 2 : if o.Cache != nil {
1396 2 : cacheSize = o.Cache.MaxSize()
1397 2 : }
1398 :
1399 2 : fmt.Fprintf(&buf, "[Version]\n")
1400 2 : fmt.Fprintf(&buf, " pebble_version=0.1\n")
1401 2 : fmt.Fprintf(&buf, "\n")
1402 2 : fmt.Fprintf(&buf, "[Options]\n")
1403 2 : fmt.Fprintf(&buf, " bytes_per_sync=%d\n", o.BytesPerSync)
1404 2 : fmt.Fprintf(&buf, " cache_size=%d\n", cacheSize)
1405 2 : fmt.Fprintf(&buf, " cleaner=%s\n", o.Cleaner)
1406 2 : fmt.Fprintf(&buf, " compaction_debt_concurrency=%d\n", o.Experimental.CompactionDebtConcurrency)
1407 2 : fmt.Fprintf(&buf, " comparer=%s\n", o.Comparer.Name)
1408 2 : fmt.Fprintf(&buf, " disable_wal=%t\n", o.DisableWAL)
1409 2 : if o.Experimental.DisableIngestAsFlushable != nil && o.Experimental.DisableIngestAsFlushable() {
1410 2 : fmt.Fprintf(&buf, " disable_ingest_as_flushable=%t\n", true)
1411 2 : }
1412 2 : if o.Experimental.EnableColumnarBlocks != nil && o.Experimental.EnableColumnarBlocks() {
1413 2 : fmt.Fprintf(&buf, " enable_columnar_blocks=%t\n", true)
1414 2 : }
1415 2 : fmt.Fprintf(&buf, " flush_delay_delete_range=%s\n", o.FlushDelayDeleteRange)
1416 2 : fmt.Fprintf(&buf, " flush_delay_range_key=%s\n", o.FlushDelayRangeKey)
1417 2 : fmt.Fprintf(&buf, " flush_split_bytes=%d\n", o.FlushSplitBytes)
1418 2 : fmt.Fprintf(&buf, " format_major_version=%d\n", o.FormatMajorVersion)
1419 2 : fmt.Fprintf(&buf, " key_schema=%s\n", o.KeySchema)
1420 2 : fmt.Fprintf(&buf, " l0_compaction_concurrency=%d\n", o.Experimental.L0CompactionConcurrency)
1421 2 : fmt.Fprintf(&buf, " l0_compaction_file_threshold=%d\n", o.L0CompactionFileThreshold)
1422 2 : fmt.Fprintf(&buf, " l0_compaction_threshold=%d\n", o.L0CompactionThreshold)
1423 2 : fmt.Fprintf(&buf, " l0_stop_writes_threshold=%d\n", o.L0StopWritesThreshold)
1424 2 : fmt.Fprintf(&buf, " lbase_max_bytes=%d\n", o.LBaseMaxBytes)
1425 2 : if o.Experimental.LevelMultiplier != defaultLevelMultiplier {
1426 2 : fmt.Fprintf(&buf, " level_multiplier=%d\n", o.Experimental.LevelMultiplier)
1427 2 : }
1428 2 : fmt.Fprintf(&buf, " max_concurrent_compactions=%d\n", o.MaxConcurrentCompactions())
1429 2 : fmt.Fprintf(&buf, " max_concurrent_downloads=%d\n", o.MaxConcurrentDownloads())
1430 2 : fmt.Fprintf(&buf, " max_manifest_file_size=%d\n", o.MaxManifestFileSize)
1431 2 : fmt.Fprintf(&buf, " max_open_files=%d\n", o.MaxOpenFiles)
1432 2 : fmt.Fprintf(&buf, " mem_table_size=%d\n", o.MemTableSize)
1433 2 : fmt.Fprintf(&buf, " mem_table_stop_writes_threshold=%d\n", o.MemTableStopWritesThreshold)
1434 2 : fmt.Fprintf(&buf, " min_deletion_rate=%d\n", o.TargetByteDeletionRate)
1435 2 : fmt.Fprintf(&buf, " free_space_threshold_bytes=%d\n", o.FreeSpaceThresholdBytes)
1436 2 : fmt.Fprintf(&buf, " free_space_timeframe=%s\n", o.FreeSpaceTimeframe.String())
1437 2 : fmt.Fprintf(&buf, " obsolete_bytes_max_ratio=%f\n", o.ObsoleteBytesMaxRatio)
1438 2 : fmt.Fprintf(&buf, " obsolete_bytes_timeframe=%s\n", o.ObsoleteBytesTimeframe.String())
1439 2 : fmt.Fprintf(&buf, " merger=%s\n", o.Merger.Name)
1440 2 : if o.Experimental.MultiLevelCompactionHeuristic != nil {
1441 2 : fmt.Fprintf(&buf, " multilevel_compaction_heuristic=%s\n", o.Experimental.MultiLevelCompactionHeuristic.String())
1442 2 : }
1443 2 : fmt.Fprintf(&buf, " read_compaction_rate=%d\n", o.Experimental.ReadCompactionRate)
1444 2 : fmt.Fprintf(&buf, " read_sampling_multiplier=%d\n", o.Experimental.ReadSamplingMultiplier)
1445 2 : fmt.Fprintf(&buf, " num_deletions_threshold=%d\n", o.Experimental.NumDeletionsThreshold)
1446 2 : fmt.Fprintf(&buf, " deletion_size_ratio_threshold=%f\n", o.Experimental.DeletionSizeRatioThreshold)
1447 2 : fmt.Fprintf(&buf, " tombstone_dense_compaction_threshold=%f\n", o.Experimental.TombstoneDenseCompactionThreshold)
1448 2 : // We no longer care about strict_wal_tail, but set it to true in case an
1449 2 : // older version reads the options.
1450 2 : fmt.Fprintf(&buf, " strict_wal_tail=%t\n", true)
1451 2 : fmt.Fprintf(&buf, " table_cache_shards=%d\n", o.Experimental.FileCacheShards)
1452 2 : fmt.Fprintf(&buf, " validate_on_ingest=%t\n", o.Experimental.ValidateOnIngest)
1453 2 : fmt.Fprintf(&buf, " wal_dir=%s\n", o.WALDir)
1454 2 : fmt.Fprintf(&buf, " wal_bytes_per_sync=%d\n", o.WALBytesPerSync)
1455 2 : fmt.Fprintf(&buf, " secondary_cache_size_bytes=%d\n", o.Experimental.SecondaryCacheSizeBytes)
1456 2 : fmt.Fprintf(&buf, " create_on_shared=%d\n", o.Experimental.CreateOnShared)
1457 2 :
1458 2 : // Private options.
1459 2 : //
1460 2 : // These options are only encoded if true, because we do not want them to
1461 2 : // appear in production serialized Options files, since they're testing-only
1462 2 : // options. They're only serialized when true, which still ensures that the
1463 2 : // metamorphic tests may propagate them to subprocesses.
1464 2 : if o.private.disableDeleteOnlyCompactions {
1465 2 : fmt.Fprintln(&buf, " disable_delete_only_compactions=true")
1466 2 : }
1467 2 : if o.private.disableElisionOnlyCompactions {
1468 2 : fmt.Fprintln(&buf, " disable_elision_only_compactions=true")
1469 2 : }
1470 2 : if o.private.disableLazyCombinedIteration {
1471 2 : fmt.Fprintln(&buf, " disable_lazy_combined_iteration=true")
1472 2 : }
1473 :
1474 2 : if o.WALFailover != nil {
1475 2 : unhealthyThreshold, _ := o.WALFailover.FailoverOptions.UnhealthyOperationLatencyThreshold()
1476 2 : fmt.Fprintf(&buf, "\n")
1477 2 : fmt.Fprintf(&buf, "[WAL Failover]\n")
1478 2 : fmt.Fprintf(&buf, " secondary_dir=%s\n", o.WALFailover.Secondary.Dirname)
1479 2 : fmt.Fprintf(&buf, " primary_dir_probe_interval=%s\n", o.WALFailover.FailoverOptions.PrimaryDirProbeInterval)
1480 2 : fmt.Fprintf(&buf, " healthy_probe_latency_threshold=%s\n", o.WALFailover.FailoverOptions.HealthyProbeLatencyThreshold)
1481 2 : fmt.Fprintf(&buf, " healthy_interval=%s\n", o.WALFailover.FailoverOptions.HealthyInterval)
1482 2 : fmt.Fprintf(&buf, " unhealthy_sampling_interval=%s\n", o.WALFailover.FailoverOptions.UnhealthySamplingInterval)
1483 2 : fmt.Fprintf(&buf, " unhealthy_operation_latency_threshold=%s\n", unhealthyThreshold)
1484 2 : fmt.Fprintf(&buf, " elevated_write_stall_threshold_lag=%s\n", o.WALFailover.FailoverOptions.ElevatedWriteStallThresholdLag)
1485 2 : }
1486 :
1487 2 : for i := range o.Levels {
1488 2 : l := &o.Levels[i]
1489 2 : fmt.Fprintf(&buf, "\n")
1490 2 : fmt.Fprintf(&buf, "[Level \"%d\"]\n", i)
1491 2 : fmt.Fprintf(&buf, " block_restart_interval=%d\n", l.BlockRestartInterval)
1492 2 : fmt.Fprintf(&buf, " block_size=%d\n", l.BlockSize)
1493 2 : fmt.Fprintf(&buf, " block_size_threshold=%d\n", l.BlockSizeThreshold)
1494 2 : fmt.Fprintf(&buf, " compression=%s\n", resolveDefaultCompression(l.Compression()))
1495 2 : fmt.Fprintf(&buf, " filter_policy=%s\n", filterPolicyName(l.FilterPolicy))
1496 2 : fmt.Fprintf(&buf, " filter_type=%s\n", l.FilterType)
1497 2 : fmt.Fprintf(&buf, " index_block_size=%d\n", l.IndexBlockSize)
1498 2 : fmt.Fprintf(&buf, " target_file_size=%d\n", l.TargetFileSize)
1499 2 : }
1500 :
1501 2 : return buf.String()
1502 : }
1503 :
1504 : type parseOptionsFuncs struct {
1505 : visitNewSection func(i, j int, section string) error
1506 : visitKeyValue func(i, j int, section, key, value string) error
1507 : visitCommentOrWhitespace func(i, j int, whitespace string) error
1508 : }
1509 :
1510 : // parseOptions takes options serialized by Options.String() and parses them
1511 : // into keys and values. It calls fns.visitNewSection for the beginning of each
1512 : // new section, fns.visitKeyValue for each key-value pair, and
1513 : // visitCommentOrWhitespace for comments and whitespace between key-value pairs.
1514 2 : func parseOptions(s string, fns parseOptionsFuncs) error {
1515 2 : var section, mappedSection string
1516 2 : i := 0
1517 2 : for i < len(s) {
1518 2 : rem := s[i:]
1519 2 : j := strings.IndexByte(rem, '\n')
1520 2 : if j < 0 {
1521 1 : j = len(rem)
1522 2 : } else {
1523 2 : j += 1 // Include the newline.
1524 2 : }
1525 2 : line := strings.TrimSpace(s[i : i+j])
1526 2 : startOff, endOff := i, i+j
1527 2 : i += j
1528 2 :
1529 2 : if len(line) == 0 || line[0] == ';' || line[0] == '#' {
1530 2 : // Skip blank lines and comments.
1531 2 : if fns.visitCommentOrWhitespace != nil {
1532 2 : if err := fns.visitCommentOrWhitespace(startOff, endOff, line); err != nil {
1533 0 : return err
1534 0 : }
1535 : }
1536 2 : continue
1537 : }
1538 2 : n := len(line)
1539 2 : if line[0] == '[' && line[n-1] == ']' {
1540 2 : // Parse section.
1541 2 : section = line[1 : n-1]
1542 2 : // RocksDB uses a similar (INI-style) syntax for the OPTIONS file, but
1543 2 : // different section names and keys. The "CFOptions ..." paths are the
1544 2 : // RocksDB versions which we map to the Pebble paths.
1545 2 : mappedSection = section
1546 2 : if section == `CFOptions "default"` {
1547 1 : mappedSection = "Options"
1548 1 : }
1549 2 : if fns.visitNewSection != nil {
1550 2 : if err := fns.visitNewSection(startOff, endOff, mappedSection); err != nil {
1551 0 : return err
1552 0 : }
1553 : }
1554 2 : continue
1555 : }
1556 :
1557 2 : pos := strings.Index(line, "=")
1558 2 : if pos < 0 {
1559 1 : const maxLen = 50
1560 1 : if len(line) > maxLen {
1561 0 : line = line[:maxLen-3] + "..."
1562 0 : }
1563 1 : return base.CorruptionErrorf("invalid key=value syntax: %q", errors.Safe(line))
1564 : }
1565 :
1566 2 : key := strings.TrimSpace(line[:pos])
1567 2 : value := strings.TrimSpace(line[pos+1:])
1568 2 :
1569 2 : if section == `CFOptions "default"` {
1570 1 : switch key {
1571 1 : case "comparator":
1572 1 : key = "comparer"
1573 1 : case "merge_operator":
1574 1 : key = "merger"
1575 : }
1576 : }
1577 2 : if fns.visitKeyValue != nil {
1578 2 : if err := fns.visitKeyValue(startOff, endOff, mappedSection, key, value); err != nil {
1579 1 : return err
1580 1 : }
1581 : }
1582 : }
1583 2 : return nil
1584 : }
1585 :
1586 : // ParseHooks contains callbacks to create options fields which can have
1587 : // user-defined implementations.
1588 : type ParseHooks struct {
1589 : NewCleaner func(name string) (Cleaner, error)
1590 : NewComparer func(name string) (*Comparer, error)
1591 : NewFilterPolicy func(name string) (FilterPolicy, error)
1592 : NewKeySchema func(name string) (KeySchema, error)
1593 : NewMerger func(name string) (*Merger, error)
1594 : SkipUnknown func(name, value string) bool
1595 : }
1596 :
1597 : // Parse parses the options from the specified string. Note that certain
1598 : // options cannot be parsed into populated fields. For example, comparer and
1599 : // merger.
1600 2 : func (o *Options) Parse(s string, hooks *ParseHooks) error {
1601 2 : visitKeyValue := func(i, j int, section, key, value string) error {
1602 2 : // WARNING: DO NOT remove entries from the switches below because doing so
1603 2 : // causes a key previously written to the OPTIONS file to be considered unknown,
1604 2 : // a backwards incompatible change. Instead, leave in support for parsing the
1605 2 : // key but simply don't parse the value.
1606 2 :
1607 2 : parseComparer := func(name string) (*Comparer, error) {
1608 2 : switch name {
1609 1 : case DefaultComparer.Name:
1610 1 : return DefaultComparer, nil
1611 2 : case testkeys.Comparer.Name:
1612 2 : return testkeys.Comparer, nil
1613 2 : default:
1614 2 : if hooks != nil && hooks.NewComparer != nil {
1615 2 : return hooks.NewComparer(name)
1616 2 : }
1617 1 : return nil, nil
1618 : }
1619 : }
1620 :
1621 2 : switch {
1622 2 : case section == "Version":
1623 2 : switch key {
1624 2 : case "pebble_version":
1625 0 : default:
1626 0 : if hooks != nil && hooks.SkipUnknown != nil && hooks.SkipUnknown(section+"."+key, value) {
1627 0 : return nil
1628 0 : }
1629 0 : return errors.Errorf("pebble: unknown option: %s.%s",
1630 0 : errors.Safe(section), errors.Safe(key))
1631 : }
1632 2 : return nil
1633 :
1634 2 : case section == "Options":
1635 2 : var err error
1636 2 : switch key {
1637 2 : case "bytes_per_sync":
1638 2 : o.BytesPerSync, err = strconv.Atoi(value)
1639 2 : case "cache_size":
1640 2 : o.CacheSize, err = strconv.ParseInt(value, 10, 64)
1641 2 : case "cleaner":
1642 2 : switch value {
1643 2 : case "archive":
1644 2 : o.Cleaner = ArchiveCleaner{}
1645 1 : case "delete":
1646 1 : o.Cleaner = DeleteCleaner{}
1647 0 : default:
1648 0 : if hooks != nil && hooks.NewCleaner != nil {
1649 0 : o.Cleaner, err = hooks.NewCleaner(value)
1650 0 : }
1651 : }
1652 2 : case "comparer":
1653 2 : var comparer *Comparer
1654 2 : comparer, err = parseComparer(value)
1655 2 : if comparer != nil {
1656 2 : o.Comparer = comparer
1657 2 : }
1658 2 : case "compaction_debt_concurrency":
1659 2 : o.Experimental.CompactionDebtConcurrency, err = strconv.ParseUint(value, 10, 64)
1660 0 : case "delete_range_flush_delay":
1661 0 : // NB: This is a deprecated serialization of the
1662 0 : // `flush_delay_delete_range`.
1663 0 : o.FlushDelayDeleteRange, err = time.ParseDuration(value)
1664 2 : case "disable_delete_only_compactions":
1665 2 : o.private.disableDeleteOnlyCompactions, err = strconv.ParseBool(value)
1666 2 : case "disable_elision_only_compactions":
1667 2 : o.private.disableElisionOnlyCompactions, err = strconv.ParseBool(value)
1668 2 : case "disable_ingest_as_flushable":
1669 2 : var v bool
1670 2 : v, err = strconv.ParseBool(value)
1671 2 : if err == nil {
1672 2 : o.Experimental.DisableIngestAsFlushable = func() bool { return v }
1673 : }
1674 2 : case "disable_lazy_combined_iteration":
1675 2 : o.private.disableLazyCombinedIteration, err = strconv.ParseBool(value)
1676 2 : case "disable_wal":
1677 2 : o.DisableWAL, err = strconv.ParseBool(value)
1678 2 : case "enable_columnar_blocks":
1679 2 : var v bool
1680 2 : if v, err = strconv.ParseBool(value); err == nil {
1681 2 : o.Experimental.EnableColumnarBlocks = func() bool { return v }
1682 : }
1683 2 : case "flush_delay_delete_range":
1684 2 : o.FlushDelayDeleteRange, err = time.ParseDuration(value)
1685 2 : case "flush_delay_range_key":
1686 2 : o.FlushDelayRangeKey, err = time.ParseDuration(value)
1687 2 : case "flush_split_bytes":
1688 2 : o.FlushSplitBytes, err = strconv.ParseInt(value, 10, 64)
1689 2 : case "format_major_version":
1690 2 : // NB: The version written here may be stale. Open does
1691 2 : // not use the format major version encoded in the
1692 2 : // OPTIONS file other than to validate that the encoded
1693 2 : // version is valid right here.
1694 2 : var v uint64
1695 2 : v, err = strconv.ParseUint(value, 10, 64)
1696 2 : if vers := FormatMajorVersion(v); vers > internalFormatNewest || vers == FormatDefault {
1697 0 : err = errors.Newf("unsupported format major version %d", o.FormatMajorVersion)
1698 0 : }
1699 2 : if err == nil {
1700 2 : o.FormatMajorVersion = FormatMajorVersion(v)
1701 2 : }
1702 2 : case "key_schema":
1703 2 : o.KeySchema = value
1704 2 : if o.KeySchemas == nil {
1705 1 : o.KeySchemas = make(map[string]*KeySchema)
1706 1 : }
1707 2 : if _, ok := o.KeySchemas[o.KeySchema]; !ok {
1708 1 : if strings.HasPrefix(value, "DefaultKeySchema(") && strings.HasSuffix(value, ")") {
1709 1 : argsStr := strings.TrimSuffix(strings.TrimPrefix(value, "DefaultKeySchema("), ")")
1710 1 : args := strings.FieldsFunc(argsStr, func(r rune) bool {
1711 1 : return unicode.IsSpace(r) || r == ','
1712 1 : })
1713 1 : var comparer *base.Comparer
1714 1 : var bundleSize int
1715 1 : comparer, err = parseComparer(args[0])
1716 1 : if err == nil {
1717 1 : bundleSize, err = strconv.Atoi(args[1])
1718 1 : }
1719 1 : if err == nil {
1720 1 : schema := colblk.DefaultKeySchema(comparer, bundleSize)
1721 1 : o.KeySchema = schema.Name
1722 1 : o.KeySchemas[o.KeySchema] = &schema
1723 1 : }
1724 0 : } else if hooks != nil && hooks.NewKeySchema != nil {
1725 0 : var schema KeySchema
1726 0 : schema, err = hooks.NewKeySchema(value)
1727 0 : if err == nil {
1728 0 : o.KeySchemas[value] = &schema
1729 0 : }
1730 : }
1731 : }
1732 2 : case "l0_compaction_concurrency":
1733 2 : o.Experimental.L0CompactionConcurrency, err = strconv.Atoi(value)
1734 2 : case "l0_compaction_file_threshold":
1735 2 : o.L0CompactionFileThreshold, err = strconv.Atoi(value)
1736 2 : case "l0_compaction_threshold":
1737 2 : o.L0CompactionThreshold, err = strconv.Atoi(value)
1738 2 : case "l0_stop_writes_threshold":
1739 2 : o.L0StopWritesThreshold, err = strconv.Atoi(value)
1740 0 : case "l0_sublevel_compactions":
1741 : // Do nothing; option existed in older versions of pebble.
1742 2 : case "lbase_max_bytes":
1743 2 : o.LBaseMaxBytes, err = strconv.ParseInt(value, 10, 64)
1744 2 : case "level_multiplier":
1745 2 : o.Experimental.LevelMultiplier, err = strconv.Atoi(value)
1746 2 : case "max_concurrent_compactions":
1747 2 : var concurrentCompactions int
1748 2 : concurrentCompactions, err = strconv.Atoi(value)
1749 2 : if concurrentCompactions <= 0 {
1750 0 : err = errors.New("max_concurrent_compactions cannot be <= 0")
1751 2 : } else {
1752 2 : o.MaxConcurrentCompactions = func() int { return concurrentCompactions }
1753 : }
1754 2 : case "max_concurrent_downloads":
1755 2 : var concurrentDownloads int
1756 2 : concurrentDownloads, err = strconv.Atoi(value)
1757 2 : if concurrentDownloads <= 0 {
1758 0 : err = errors.New("max_concurrent_compactions cannot be <= 0")
1759 2 : } else {
1760 2 : o.MaxConcurrentDownloads = func() int { return concurrentDownloads }
1761 : }
1762 2 : case "max_manifest_file_size":
1763 2 : o.MaxManifestFileSize, err = strconv.ParseInt(value, 10, 64)
1764 2 : case "max_open_files":
1765 2 : o.MaxOpenFiles, err = strconv.Atoi(value)
1766 2 : case "mem_table_size":
1767 2 : o.MemTableSize, err = strconv.ParseUint(value, 10, 64)
1768 2 : case "mem_table_stop_writes_threshold":
1769 2 : o.MemTableStopWritesThreshold, err = strconv.Atoi(value)
1770 0 : case "min_compaction_rate":
1771 : // Do nothing; option existed in older versions of pebble, and
1772 : // may be meaningful again eventually.
1773 2 : case "min_deletion_rate":
1774 2 : o.TargetByteDeletionRate, err = strconv.Atoi(value)
1775 2 : case "free_space_threshold_bytes":
1776 2 : o.FreeSpaceThresholdBytes, err = strconv.ParseUint(value, 10, 64)
1777 2 : case "free_space_timeframe":
1778 2 : o.FreeSpaceTimeframe, err = time.ParseDuration(value)
1779 2 : case "obsolete_bytes_max_ratio":
1780 2 : o.ObsoleteBytesMaxRatio, err = strconv.ParseFloat(value, 64)
1781 2 : case "obsolete_bytes_timeframe":
1782 2 : o.ObsoleteBytesTimeframe, err = time.ParseDuration(value)
1783 0 : case "min_flush_rate":
1784 : // Do nothing; option existed in older versions of pebble, and
1785 : // may be meaningful again eventually.
1786 2 : case "multilevel_compaction_heuristic":
1787 2 : switch {
1788 2 : case value == "none":
1789 2 : o.Experimental.MultiLevelCompactionHeuristic = NoMultiLevel{}
1790 2 : case strings.HasPrefix(value, "wamp"):
1791 2 : fields := strings.FieldsFunc(strings.TrimPrefix(value, "wamp"), func(r rune) bool {
1792 2 : return unicode.IsSpace(r) || r == ',' || r == '(' || r == ')'
1793 2 : })
1794 2 : if len(fields) != 2 {
1795 0 : err = errors.Newf("require 2 arguments")
1796 0 : }
1797 2 : var h WriteAmpHeuristic
1798 2 : if err == nil {
1799 2 : h.AddPropensity, err = strconv.ParseFloat(fields[0], 64)
1800 2 : }
1801 2 : if err == nil {
1802 2 : h.AllowL0, err = strconv.ParseBool(fields[1])
1803 2 : }
1804 2 : if err == nil {
1805 2 : o.Experimental.MultiLevelCompactionHeuristic = h
1806 2 : } else {
1807 0 : err = errors.Wrapf(err, "unexpected wamp heuristic arguments: %s", value)
1808 0 : }
1809 0 : default:
1810 0 : err = errors.Newf("unrecognized multilevel compaction heuristic: %s", value)
1811 : }
1812 0 : case "point_tombstone_weight":
1813 : // Do nothing; deprecated.
1814 2 : case "strict_wal_tail":
1815 2 : var strictWALTail bool
1816 2 : strictWALTail, err = strconv.ParseBool(value)
1817 2 : if err == nil && !strictWALTail {
1818 0 : err = errors.Newf("reading from versions with strict_wal_tail=false no longer supported")
1819 0 : }
1820 2 : case "merger":
1821 2 : switch value {
1822 0 : case "nullptr":
1823 0 : o.Merger = nil
1824 2 : case "pebble.concatenate":
1825 2 : o.Merger = DefaultMerger
1826 1 : default:
1827 1 : if hooks != nil && hooks.NewMerger != nil {
1828 1 : o.Merger, err = hooks.NewMerger(value)
1829 1 : }
1830 : }
1831 2 : case "read_compaction_rate":
1832 2 : o.Experimental.ReadCompactionRate, err = strconv.ParseInt(value, 10, 64)
1833 2 : case "read_sampling_multiplier":
1834 2 : o.Experimental.ReadSamplingMultiplier, err = strconv.ParseInt(value, 10, 64)
1835 2 : case "num_deletions_threshold":
1836 2 : o.Experimental.NumDeletionsThreshold, err = strconv.Atoi(value)
1837 2 : case "deletion_size_ratio_threshold":
1838 2 : val, parseErr := strconv.ParseFloat(value, 32)
1839 2 : o.Experimental.DeletionSizeRatioThreshold = float32(val)
1840 2 : err = parseErr
1841 2 : case "tombstone_dense_compaction_threshold":
1842 2 : o.Experimental.TombstoneDenseCompactionThreshold, err = strconv.ParseFloat(value, 64)
1843 2 : case "table_cache_shards":
1844 2 : o.Experimental.FileCacheShards, err = strconv.Atoi(value)
1845 0 : case "table_format":
1846 0 : switch value {
1847 0 : case "leveldb":
1848 0 : case "rocksdbv2":
1849 0 : default:
1850 0 : return errors.Errorf("pebble: unknown table format: %q", errors.Safe(value))
1851 : }
1852 1 : case "table_property_collectors":
1853 : // No longer implemented; ignore.
1854 2 : case "validate_on_ingest":
1855 2 : o.Experimental.ValidateOnIngest, err = strconv.ParseBool(value)
1856 2 : case "wal_dir":
1857 2 : o.WALDir = value
1858 2 : case "wal_bytes_per_sync":
1859 2 : o.WALBytesPerSync, err = strconv.Atoi(value)
1860 1 : case "max_writer_concurrency":
1861 : // No longer implemented; ignore.
1862 1 : case "force_writer_parallelism":
1863 : // No longer implemented; ignore.
1864 2 : case "secondary_cache_size_bytes":
1865 2 : o.Experimental.SecondaryCacheSizeBytes, err = strconv.ParseInt(value, 10, 64)
1866 2 : case "create_on_shared":
1867 2 : var createOnSharedInt int64
1868 2 : createOnSharedInt, err = strconv.ParseInt(value, 10, 64)
1869 2 : o.Experimental.CreateOnShared = remote.CreateOnSharedStrategy(createOnSharedInt)
1870 0 : default:
1871 0 : if hooks != nil && hooks.SkipUnknown != nil && hooks.SkipUnknown(section+"."+key, value) {
1872 0 : return nil
1873 0 : }
1874 0 : return errors.Errorf("pebble: unknown option: %s.%s",
1875 0 : errors.Safe(section), errors.Safe(key))
1876 : }
1877 2 : return err
1878 :
1879 2 : case section == "WAL Failover":
1880 2 : if o.WALFailover == nil {
1881 2 : o.WALFailover = new(WALFailoverOptions)
1882 2 : }
1883 2 : var err error
1884 2 : switch key {
1885 2 : case "secondary_dir":
1886 2 : o.WALFailover.Secondary = wal.Dir{Dirname: value, FS: vfs.Default}
1887 2 : case "primary_dir_probe_interval":
1888 2 : o.WALFailover.PrimaryDirProbeInterval, err = time.ParseDuration(value)
1889 2 : case "healthy_probe_latency_threshold":
1890 2 : o.WALFailover.HealthyProbeLatencyThreshold, err = time.ParseDuration(value)
1891 2 : case "healthy_interval":
1892 2 : o.WALFailover.HealthyInterval, err = time.ParseDuration(value)
1893 2 : case "unhealthy_sampling_interval":
1894 2 : o.WALFailover.UnhealthySamplingInterval, err = time.ParseDuration(value)
1895 2 : case "unhealthy_operation_latency_threshold":
1896 2 : var threshold time.Duration
1897 2 : threshold, err = time.ParseDuration(value)
1898 2 : o.WALFailover.UnhealthyOperationLatencyThreshold = func() (time.Duration, bool) {
1899 2 : return threshold, true
1900 2 : }
1901 2 : case "elevated_write_stall_threshold_lag":
1902 2 : o.WALFailover.ElevatedWriteStallThresholdLag, err = time.ParseDuration(value)
1903 0 : default:
1904 0 : if hooks != nil && hooks.SkipUnknown != nil && hooks.SkipUnknown(section+"."+key, value) {
1905 0 : return nil
1906 0 : }
1907 0 : return errors.Errorf("pebble: unknown option: %s.%s",
1908 0 : errors.Safe(section), errors.Safe(key))
1909 : }
1910 2 : return err
1911 :
1912 2 : case strings.HasPrefix(section, "Level "):
1913 2 : var index int
1914 2 : if n, err := fmt.Sscanf(section, `Level "%d"`, &index); err != nil {
1915 0 : return err
1916 2 : } else if n != 1 {
1917 0 : if hooks != nil && hooks.SkipUnknown != nil && hooks.SkipUnknown(section, value) {
1918 0 : return nil
1919 0 : }
1920 0 : return errors.Errorf("pebble: unknown section: %q", errors.Safe(section))
1921 : }
1922 :
1923 2 : if len(o.Levels) <= index {
1924 1 : newLevels := make([]LevelOptions, index+1)
1925 1 : copy(newLevels, o.Levels)
1926 1 : o.Levels = newLevels
1927 1 : }
1928 2 : l := &o.Levels[index]
1929 2 :
1930 2 : var err error
1931 2 : switch key {
1932 2 : case "block_restart_interval":
1933 2 : l.BlockRestartInterval, err = strconv.Atoi(value)
1934 2 : case "block_size":
1935 2 : l.BlockSize, err = strconv.Atoi(value)
1936 2 : case "block_size_threshold":
1937 2 : l.BlockSizeThreshold, err = strconv.Atoi(value)
1938 2 : case "compression":
1939 2 : switch value {
1940 0 : case "Default":
1941 0 : l.Compression = func() Compression { return DefaultCompression }
1942 2 : case "NoCompression":
1943 2 : l.Compression = func() Compression { return NoCompression }
1944 2 : case "Snappy":
1945 2 : l.Compression = func() Compression { return SnappyCompression }
1946 2 : case "ZSTD":
1947 2 : l.Compression = func() Compression { return ZstdCompression }
1948 0 : default:
1949 0 : return errors.Errorf("pebble: unknown compression: %q", errors.Safe(value))
1950 : }
1951 2 : case "filter_policy":
1952 2 : if hooks != nil && hooks.NewFilterPolicy != nil {
1953 2 : l.FilterPolicy, err = hooks.NewFilterPolicy(value)
1954 2 : }
1955 2 : case "filter_type":
1956 2 : switch value {
1957 2 : case "table":
1958 2 : l.FilterType = TableFilter
1959 0 : default:
1960 0 : return errors.Errorf("pebble: unknown filter type: %q", errors.Safe(value))
1961 : }
1962 2 : case "index_block_size":
1963 2 : l.IndexBlockSize, err = strconv.Atoi(value)
1964 2 : case "target_file_size":
1965 2 : l.TargetFileSize, err = strconv.ParseInt(value, 10, 64)
1966 0 : default:
1967 0 : if hooks != nil && hooks.SkipUnknown != nil && hooks.SkipUnknown(section+"."+key, value) {
1968 0 : return nil
1969 0 : }
1970 0 : return errors.Errorf("pebble: unknown option: %s.%s", errors.Safe(section), errors.Safe(key))
1971 : }
1972 2 : return err
1973 : }
1974 2 : if hooks != nil && hooks.SkipUnknown != nil && hooks.SkipUnknown(section+"."+key, value) {
1975 2 : return nil
1976 2 : }
1977 0 : return errors.Errorf("pebble: unknown section: %q", errors.Safe(section))
1978 : }
1979 2 : return parseOptions(s, parseOptionsFuncs{
1980 2 : visitKeyValue: visitKeyValue,
1981 2 : })
1982 : }
1983 :
1984 : // ErrMissingWALRecoveryDir is an error returned when a database is attempted to be
1985 : // opened without supplying a Options.WALRecoveryDir entry for a directory that
1986 : // may contain WALs required to recover a consistent database state.
1987 : type ErrMissingWALRecoveryDir struct {
1988 : Dir string
1989 : }
1990 :
1991 : // Error implements error.
1992 1 : func (e ErrMissingWALRecoveryDir) Error() string {
1993 1 : return fmt.Sprintf("directory %q may contain relevant WALs", e.Dir)
1994 1 : }
1995 :
1996 : // CheckCompatibility verifies the options are compatible with the previous options
1997 : // serialized by Options.String(). For example, the Comparer and Merger must be
1998 : // the same, or data will not be able to be properly read from the DB.
1999 : //
2000 : // This function only looks at specific keys and does not error out if the
2001 : // options are newer and contain unknown keys.
2002 2 : func (o *Options) CheckCompatibility(previousOptions string) error {
2003 2 : visitKeyValue := func(i, j int, section, key, value string) error {
2004 2 : switch section + "." + key {
2005 2 : case "Options.comparer":
2006 2 : if value != o.Comparer.Name {
2007 1 : return errors.Errorf("pebble: comparer name from file %q != comparer name from options %q",
2008 1 : errors.Safe(value), errors.Safe(o.Comparer.Name))
2009 1 : }
2010 2 : case "Options.merger":
2011 2 : // RocksDB allows the merge operator to be unspecified, in which case it
2012 2 : // shows up as "nullptr".
2013 2 : if value != "nullptr" && value != o.Merger.Name {
2014 1 : return errors.Errorf("pebble: merger name from file %q != merger name from options %q",
2015 1 : errors.Safe(value), errors.Safe(o.Merger.Name))
2016 1 : }
2017 2 : case "Options.wal_dir", "WAL Failover.secondary_dir":
2018 2 : switch {
2019 2 : case o.WALDir == value:
2020 2 : return nil
2021 2 : case o.WALFailover != nil && o.WALFailover.Secondary.Dirname == value:
2022 2 : return nil
2023 1 : default:
2024 1 : for _, d := range o.WALRecoveryDirs {
2025 1 : if d.Dirname == value {
2026 1 : return nil
2027 1 : }
2028 : }
2029 1 : return ErrMissingWALRecoveryDir{Dir: value}
2030 : }
2031 : }
2032 2 : return nil
2033 : }
2034 2 : return parseOptions(previousOptions, parseOptionsFuncs{visitKeyValue: visitKeyValue})
2035 : }
2036 :
2037 : // Validate verifies that the options are mutually consistent. For example,
2038 : // L0StopWritesThreshold must be >= L0CompactionThreshold, otherwise a write
2039 : // stall would persist indefinitely.
2040 2 : func (o *Options) Validate() error {
2041 2 : // Note that we can presume Options.EnsureDefaults has been called, so there
2042 2 : // is no need to check for zero values.
2043 2 :
2044 2 : var buf strings.Builder
2045 2 : if o.Experimental.L0CompactionConcurrency < 1 {
2046 1 : fmt.Fprintf(&buf, "L0CompactionConcurrency (%d) must be >= 1\n",
2047 1 : o.Experimental.L0CompactionConcurrency)
2048 1 : }
2049 2 : if o.L0StopWritesThreshold < o.L0CompactionThreshold {
2050 1 : fmt.Fprintf(&buf, "L0StopWritesThreshold (%d) must be >= L0CompactionThreshold (%d)\n",
2051 1 : o.L0StopWritesThreshold, o.L0CompactionThreshold)
2052 1 : }
2053 2 : if uint64(o.MemTableSize) >= maxMemTableSize {
2054 1 : fmt.Fprintf(&buf, "MemTableSize (%s) must be < %s\n",
2055 1 : humanize.Bytes.Uint64(uint64(o.MemTableSize)), humanize.Bytes.Uint64(maxMemTableSize))
2056 1 : }
2057 2 : if o.MemTableStopWritesThreshold < 2 {
2058 1 : fmt.Fprintf(&buf, "MemTableStopWritesThreshold (%d) must be >= 2\n",
2059 1 : o.MemTableStopWritesThreshold)
2060 1 : }
2061 2 : if o.FormatMajorVersion < FormatMinSupported || o.FormatMajorVersion > internalFormatNewest {
2062 0 : fmt.Fprintf(&buf, "FormatMajorVersion (%d) must be between %d and %d\n",
2063 0 : o.FormatMajorVersion, FormatMinSupported, internalFormatNewest)
2064 0 : }
2065 2 : if o.Experimental.CreateOnShared != remote.CreateOnSharedNone && o.FormatMajorVersion < FormatMinForSharedObjects {
2066 0 : fmt.Fprintf(&buf, "FormatMajorVersion (%d) when CreateOnShared is set must be at least %d\n",
2067 0 : o.FormatMajorVersion, FormatMinForSharedObjects)
2068 0 : }
2069 2 : if len(o.KeySchemas) > 0 {
2070 2 : if o.KeySchema == "" {
2071 0 : fmt.Fprintf(&buf, "KeySchemas is set but KeySchema is not\n")
2072 0 : }
2073 2 : if _, ok := o.KeySchemas[o.KeySchema]; !ok {
2074 0 : fmt.Fprintf(&buf, "KeySchema %q not found in KeySchemas\n", o.KeySchema)
2075 0 : }
2076 : }
2077 2 : if buf.Len() == 0 {
2078 2 : return nil
2079 2 : }
2080 1 : return errors.New(buf.String())
2081 : }
2082 :
2083 : // MakeReaderOptions constructs sstable.ReaderOptions from the corresponding
2084 : // options in the receiver.
2085 2 : func (o *Options) MakeReaderOptions() sstable.ReaderOptions {
2086 2 : var readerOpts sstable.ReaderOptions
2087 2 : if o != nil {
2088 2 : readerOpts.Comparer = o.Comparer
2089 2 : readerOpts.Filters = o.Filters
2090 2 : readerOpts.KeySchemas = o.KeySchemas
2091 2 : readerOpts.LoadBlockSema = o.LoadBlockSema
2092 2 : readerOpts.LoggerAndTracer = o.LoggerAndTracer
2093 2 : readerOpts.Merger = o.Merger
2094 2 : }
2095 2 : return readerOpts
2096 : }
2097 :
2098 : // MakeWriterOptions constructs sstable.WriterOptions for the specified level
2099 : // from the corresponding options in the receiver.
2100 2 : func (o *Options) MakeWriterOptions(level int, format sstable.TableFormat) sstable.WriterOptions {
2101 2 : var writerOpts sstable.WriterOptions
2102 2 : writerOpts.TableFormat = format
2103 2 : if o != nil {
2104 2 : writerOpts.Comparer = o.Comparer
2105 2 : if o.Merger != nil {
2106 2 : writerOpts.MergerName = o.Merger.Name
2107 2 : }
2108 2 : writerOpts.BlockPropertyCollectors = o.BlockPropertyCollectors
2109 : }
2110 2 : if format >= sstable.TableFormatPebblev3 {
2111 2 : writerOpts.ShortAttributeExtractor = o.Experimental.ShortAttributeExtractor
2112 2 : writerOpts.RequiredInPlaceValueBound = o.Experimental.RequiredInPlaceValueBound
2113 2 : if format >= sstable.TableFormatPebblev4 && level == numLevels-1 {
2114 2 : writerOpts.WritingToLowestLevel = true
2115 2 : }
2116 : }
2117 2 : levelOpts := o.Level(level)
2118 2 : writerOpts.BlockRestartInterval = levelOpts.BlockRestartInterval
2119 2 : writerOpts.BlockSize = levelOpts.BlockSize
2120 2 : writerOpts.BlockSizeThreshold = levelOpts.BlockSizeThreshold
2121 2 : writerOpts.Compression = resolveDefaultCompression(levelOpts.Compression())
2122 2 : writerOpts.FilterPolicy = levelOpts.FilterPolicy
2123 2 : writerOpts.FilterType = levelOpts.FilterType
2124 2 : writerOpts.IndexBlockSize = levelOpts.IndexBlockSize
2125 2 : writerOpts.KeySchema = o.KeySchemas[o.KeySchema]
2126 2 : writerOpts.AllocatorSizeClasses = o.AllocatorSizeClasses
2127 2 : writerOpts.NumDeletionsThreshold = o.Experimental.NumDeletionsThreshold
2128 2 : writerOpts.DeletionSizeRatioThreshold = o.Experimental.DeletionSizeRatioThreshold
2129 2 : return writerOpts
2130 : }
2131 :
2132 : // MakeBlobWriterOptions constructs blob.FileWriterOptions from the corresponding
2133 : // options in the receiver.
2134 1 : func (o *Options) MakeBlobWriterOptions(level int) blob.FileWriterOptions {
2135 1 : lo := o.Level(level)
2136 1 : return blob.FileWriterOptions{
2137 1 : Compression: resolveDefaultCompression(lo.Compression()),
2138 1 : ChecksumType: block.ChecksumTypeCRC32c,
2139 1 : FlushGovernor: block.MakeFlushGovernor(
2140 1 : lo.BlockSize,
2141 1 : lo.BlockSizeThreshold,
2142 1 : base.SizeClassAwareBlockSizeThreshold,
2143 1 : o.AllocatorSizeClasses,
2144 1 : ),
2145 1 : }
2146 1 : }
2147 :
2148 2 : func resolveDefaultCompression(c Compression) Compression {
2149 2 : if c <= DefaultCompression || c >= block.NCompression {
2150 1 : c = SnappyCompression
2151 1 : }
2152 2 : return c
2153 : }
2154 :
2155 : // UserKeyCategories describes a partitioning of the user key space. Each
2156 : // partition is a category with a name. The categories are used for informative
2157 : // purposes only (like pprof labels). Pebble does not treat keys differently
2158 : // based on the UserKeyCategories.
2159 : //
2160 : // The partitions are defined by their upper bounds. The last partition is
2161 : // assumed to go until the end of keyspace; its UpperBound is ignored. The rest
2162 : // of the partitions are ordered by their UpperBound.
2163 : type UserKeyCategories struct {
2164 : categories []UserKeyCategory
2165 : cmp base.Compare
2166 : // rangeNames[i][j] contains the string referring to the categories in the
2167 : // range [i, j], with j > i.
2168 : rangeNames [][]string
2169 : }
2170 :
2171 : // UserKeyCategory describes a partition of the user key space.
2172 : //
2173 : // User keys >= the previous category's UpperBound and < this category's
2174 : // UpperBound are part of this category.
2175 : type UserKeyCategory struct {
2176 : Name string
2177 : // UpperBound is the exclusive upper bound of the category. All user keys >= the
2178 : // previous category's UpperBound and < this UpperBound are part of this
2179 : // category.
2180 : UpperBound []byte
2181 : }
2182 :
2183 : // MakeUserKeyCategories creates a UserKeyCategories object with the given
2184 : // categories. The object is immutable and can be reused across different
2185 : // stores.
2186 1 : func MakeUserKeyCategories(cmp base.Compare, categories ...UserKeyCategory) UserKeyCategories {
2187 1 : n := len(categories)
2188 1 : if n == 0 {
2189 0 : return UserKeyCategories{}
2190 0 : }
2191 1 : if categories[n-1].UpperBound != nil {
2192 0 : panic("last category UpperBound must be nil")
2193 : }
2194 : // Verify that the partitions are ordered as expected.
2195 1 : for i := 1; i < n-1; i++ {
2196 1 : if cmp(categories[i-1].UpperBound, categories[i].UpperBound) >= 0 {
2197 0 : panic("invalid UserKeyCategories: key prefixes must be sorted")
2198 : }
2199 : }
2200 :
2201 : // Precalculate a table of range names to avoid allocations in the
2202 : // categorization path.
2203 1 : rangeNamesBuf := make([]string, n*n)
2204 1 : rangeNames := make([][]string, n)
2205 1 : for i := range rangeNames {
2206 1 : rangeNames[i] = rangeNamesBuf[:n]
2207 1 : rangeNamesBuf = rangeNamesBuf[n:]
2208 1 : for j := i + 1; j < n; j++ {
2209 1 : rangeNames[i][j] = categories[i].Name + "-" + categories[j].Name
2210 1 : }
2211 : }
2212 1 : return UserKeyCategories{
2213 1 : categories: categories,
2214 1 : cmp: cmp,
2215 1 : rangeNames: rangeNames,
2216 1 : }
2217 : }
2218 :
2219 : // Len returns the number of categories defined.
2220 2 : func (kc *UserKeyCategories) Len() int {
2221 2 : return len(kc.categories)
2222 2 : }
2223 :
2224 : // CategorizeKey returns the name of the category containing the key.
2225 1 : func (kc *UserKeyCategories) CategorizeKey(userKey []byte) string {
2226 1 : idx := sort.Search(len(kc.categories)-1, func(i int) bool {
2227 1 : return kc.cmp(userKey, kc.categories[i].UpperBound) < 0
2228 1 : })
2229 1 : return kc.categories[idx].Name
2230 : }
2231 :
2232 : // CategorizeKeyRange returns the name of the category containing the key range.
2233 : // If the key range spans multiple categories, the result shows the first and
2234 : // last category separated by a dash, e.g. `cat1-cat5`.
2235 1 : func (kc *UserKeyCategories) CategorizeKeyRange(startUserKey, endUserKey []byte) string {
2236 1 : n := len(kc.categories)
2237 1 : p := sort.Search(n-1, func(i int) bool {
2238 1 : return kc.cmp(startUserKey, kc.categories[i].UpperBound) < 0
2239 1 : })
2240 1 : if p == n-1 || kc.cmp(endUserKey, kc.categories[p].UpperBound) < 0 {
2241 1 : // Fast path for a single category.
2242 1 : return kc.categories[p].Name
2243 1 : }
2244 : // Binary search among the remaining categories.
2245 1 : q := p + 1 + sort.Search(n-2-p, func(i int) bool {
2246 1 : return kc.cmp(endUserKey, kc.categories[p+1+i].UpperBound) < 0
2247 1 : })
2248 1 : return kc.rangeNames[p][q]
2249 : }
|
