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