// Close frees up resources held by the iterator.

Close()

// SeekGE advances the iterator to the first key in the engine which is >= the

// provided key. This may be in the middle of a bare range key straddling the

// seek key.

SeekGE(key MVCCKey)

// Valid must be called after any call to Seek(), Next(), Prev(), or

// similar methods. It returns (true, nil) if the iterator points to

// a valid key (it is undefined to call Key(), Value(), or similar

// methods unless Valid() has returned (true, nil)). It returns

// (false, nil) if the iterator has moved past the end of the valid

// range, or (false, err) if an error has occurred. Valid() will

// never return true with a non-nil error.

Valid() (bool, error)

// Next advances the iterator to the next key in the iteration. After this

// call, Valid() will be true if the iterator was not positioned at the last

// key.

Next()

// NextKey advances the iterator to the next MVCC key. This operation is

// distinct from Next which advances to the next version of the current key

// or the next key if the iterator is currently located at the last version

// for a key. NextKey must not be used to switch iteration direction from

// reverse iteration to forward iteration.

//

// If NextKey() lands on a bare range key, it is possible that there exists a

// versioned point key at the start key too. Calling NextKey() again would

// skip over this point key, since the start key was already emitted. If the

// caller wants to see it, it must call Next() to check for it. Note that

// this is not the case with intents: they don't have a timestamp, so the

// encoded key is identical to the range key's start bound, and they will

// be emitted together at that position.

NextKey()

// UnsafeKey returns the same value as Key, but the memory is invalidated on

// the next call to {Next,NextKey,Prev,SeekGE,SeekLT,Close}.

UnsafeKey() MVCCKey

// UnsafeValue returns the same value as Value, but the memory is

// invalidated on the next call to {Next,NextKey,Prev,SeekGE,SeekLT,Close}.

UnsafeValue() []byte

// HasPointAndRange returns whether the current iterator position has a point

// key and/or a range key. Must check Valid() first. At least one of these

// will always be true for a valid iterator. For details on range keys, see

// comment on SimpleMVCCIterator.

HasPointAndRange() (bool, bool)

// RangeBounds returns the range bounds for the current range key, or an

// empty span if there are none. The returned keys are only valid until the

// next iterator call.

RangeBounds() roachpb.Span

// RangeKeys returns a stack of all range keys (with different timestamps) at

// the current key position. When at a point key, it will return all range

// keys overlapping that point key. The stack is only valid until the next

// iterator operation. For details on range keys, see comment on

// SimpleMVCCIterator, or this tech note:

// https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/mvcc-range-tombstones.md

RangeKeys() MVCCRangeKeyStack

// Iteration stats. We directly expose pebble.IteratorStats. Callers

// may want to aggregate and interpret these in the following manner:

// - Aggregate {Forward,Reverse}SeekCount, {Forward,Reverse}StepCount.

// - Interpret the four aggregated stats as follows:

// - {SeekCount,StepCount}[InterfaceCall]: We can refer to these simply as

// {SeekCount,StepCount} in logs/metrics/traces. These represents

// explicit calls by the implementation of MVCCIterator, in response to

// the caller of MVCCIterator. A high count relative to the unique MVCC

// keys returned suggests there are many versions for the same key.

// - {SeekCount,StepCount}[InternalIterCall]: We can refer to these simply

// as {InternalSeekCount,InternalStepCount}. If these are significantly

// larger than the ones in the preceding bullet, it suggests that there

// are lots of uncompacted deletes or stale Pebble-versions (not to be

// confused with MVCC versions) that need to be compacted away. This

// should be very rare, but has been observed.

Stats pebble.IteratorStats

SimpleMVCCIterator

// SeekLT advances the iterator to the first key in the engine which is < the

// provided key. Unlike SeekGE, when calling SeekLT within range key bounds

// this will not land on the seek key, but rather on the closest point key

// overlapping the range key or the range key's start bound.

SeekLT(key MVCCKey)

// Prev moves the iterator backward to the previous key in the iteration.

// After this call, Valid() will be true if the iterator was not positioned at

// the first key.

Prev()

// SeekIntentGE is a specialized version of SeekGE(MVCCKey{Key: key}), when

// the caller expects to find an intent, and additionally has the txnUUID

// for the intent it is looking for. When running with separated intents,

// this can optimize the behavior of the underlying Engine for write heavy

// keys by avoiding the need to iterate over many deleted intents.

SeekIntentGE(key roachpb.Key, txnUUID uuid.UUID)

// Key returns the current key position. This may be a point key, or

// the current position inside a range key (typically the start key

// or the seek key when using SeekGE within its bounds).

Key() MVCCKey

// UnsafeRawKey returns the current raw key which could be an encoded

// MVCCKey, or the more general EngineKey (for a lock table key).

// This is a low-level and dangerous method since it will expose the

// raw key of the lock table, i.e., the intentInterleavingIter will not

// hide the difference between interleaved and separated intents.

// Callers should be very careful when using this. This is currently

// only used by callers who are iterating and deleting all data in a

// range.

UnsafeRawKey() []byte

// UnsafeRawMVCCKey returns a serialized MVCCKey. The memory is invalidated

// on the next call to {Next,NextKey,Prev,SeekGE,SeekLT,Close}. If the

// iterator is currently positioned at a separated intent (when

// intentInterleavingIter is used), it makes that intent look like an

// interleaved intent key, i.e., an MVCCKey with an empty timestamp. This is

// currently used by callers who pass around key information as a []byte --

// this seems avoidable, and we should consider cleaning up the callers.

UnsafeRawMVCCKey() []byte

// Value returns the current point key value as a byte slice.

Value() []byte

// ValueProto unmarshals the value the iterator is currently

// pointing to using a protobuf decoder.

ValueProto(msg protoutil.Message) error

// ComputeStats scans the underlying engine from start to end keys and

// computes stats counters based on the values. This method is used after a

// range is split to recompute stats for each subrange. The nowNanos arg

// specifies the wall time in nanoseconds since the epoch and is used to

// compute the total age of intents and garbage.

//

// To properly account for intents and range keys, the iterator must be

// created with MVCCKeyAndIntentsIterKind and IterKeyTypePointsAndRanges,

// and the LowerBound and UpperBound must be set equal to start and end

// in order for range keys to be truncated to the bounds.

//

// TODO(erikgrinaker): This should be replaced by ComputeStatsForRange

// instead, which should set up its own iterator with appropriate options.

// This isn't currently done in order to do spanset assertions on it, but this

// could be better solved by checking the iterator bounds in NewMVCCIterator

// and requiring callers to set them appropriately.

ComputeStats(start, end roachpb.Key, nowNanos int64) (enginepb.MVCCStats, error)

// FindSplitKey finds a key from the given span such that the left side of

// the split is roughly targetSize bytes. The returned key will never be

// chosen from the key ranges listed in keys.NoSplitSpans and will always

// sort equal to or after minSplitKey.

//

// DO NOT CALL directly (except in wrapper MVCCIterator implementations). Use the

// package-level MVCCFindSplitKey instead. For correct operation, the caller

// must set the upper bound on the iterator before calling this method.

FindSplitKey(start, end, minSplitKey roachpb.Key, targetSize int64) (MVCCKey, error)

// Stats returns statistics about the iterator.

Stats() IteratorStats

// SupportsPrev returns true if MVCCIterator implementation supports reverse

// iteration with Prev() or SeekLT().

SupportsPrev() bool

// Close frees up resources held by the iterator.

Close()

// SeekEngineKeyGE advances the iterator to the first key in the engine

// which is >= the provided key.

SeekEngineKeyGE(key EngineKey) (valid bool, err error)

// SeekEngineKeyLT advances the iterator to the first key in the engine

// which is < the provided key.

SeekEngineKeyLT(key EngineKey) (valid bool, err error)

// NextEngineKey advances the iterator to the next key/value in the

// iteration. After this call, valid will be true if the iterator was not

// originally positioned at the last key. Note that unlike

// MVCCIterator.NextKey, this method does not skip other versions with the

// same EngineKey.Key.

// TODO(sumeer): change MVCCIterator.Next() to match the

// return values, change all its callers, and rename this

// to Next().

NextEngineKey() (valid bool, err error)

// PrevEngineKey moves the iterator backward to the previous key/value in

// the iteration. After this call, valid will be true if the iterator was

// not originally positioned at the first key.

PrevEngineKey() (valid bool, err error)

// HasPointAndRange returns whether the iterator is positioned on a point or

// range key (shared with MVCCIterator interface).

HasPointAndRange() (bool, bool)

// EngineRangeBounds returns the current range key bounds.

EngineRangeBounds() (roachpb.Span, error)

// EngineRangeKeys returns the engine range keys at the current position.

EngineRangeKeys() []EngineRangeKeyValue

// UnsafeEngineKey returns the same value as EngineKey, but the memory is

// invalidated on the next call to {Next,NextKey,Prev,SeekGE,SeekLT,Close}.

// REQUIRES: latest positioning function returned valid=true.

UnsafeEngineKey() (EngineKey, error)

// EngineKey returns the current key.

// REQUIRES: latest positioning function returned valid=true.

EngineKey() (EngineKey, error)

// UnsafeRawEngineKey returns the current raw (encoded) key corresponding to

// EngineKey. This is a low-level method and callers should avoid using

// it. This is currently only used by intentInterleavingIter to implement

// UnsafeRawKey.

UnsafeRawEngineKey() []byte

// UnsafeValue returns the same value as Value, but the memory is

// invalidated on the next call to {Next,NextKey,Prev,SeekGE,SeekLT,Close}.

// REQUIRES: latest positioning function returned valid=true.

UnsafeValue() []byte

// Value returns the current value as a byte slice.

// REQUIRES: latest positioning function returned valid=true.

Value() []byte

// GetRawIter is a low-level method only for use in the storage package,

// that returns the underlying pebble Iterator.

GetRawIter() *pebble.Iterator

// SeekEngineKeyGEWithLimit is similar to SeekEngineKeyGE, but takes an

// additional exclusive upper limit parameter. The limit is semantically

// best-effort, and is an optimization to avoid O(n^2) iteration behavior in

// some pathological situations (uncompacted deleted locks).

SeekEngineKeyGEWithLimit(key EngineKey, limit roachpb.Key) (state pebble.IterValidityState, err error)

// SeekEngineKeyLTWithLimit is similar to SeekEngineKeyLT, but takes an

// additional inclusive lower limit parameter. The limit is semantically

// best-effort, and is an optimization to avoid O(n^2) iteration behavior in

// some pathological situations (uncompacted deleted locks).

SeekEngineKeyLTWithLimit(key EngineKey, limit roachpb.Key) (state pebble.IterValidityState, err error)

// NextEngineKeyWithLimit is similar to NextEngineKey, but takes an

// additional exclusive upper limit parameter. The limit is semantically

// best-effort, and is an optimization to avoid O(n^2) iteration behavior in

// some pathological situations (uncompacted deleted locks).

NextEngineKeyWithLimit(limit roachpb.Key) (state pebble.IterValidityState, err error)

// PrevEngineKeyWithLimit is similar to PrevEngineKey, but takes an

// additional inclusive lower limit parameter. The limit is semantically

// best-effort, and is an optimization to avoid O(n^2) iteration behavior in

// some pathological situations (uncompacted deleted locks).

PrevEngineKeyWithLimit(limit roachpb.Key) (state pebble.IterValidityState, err error)

// Stats returns statistics about the iterator.

Stats() IteratorStats

// If Prefix is true, Seek will use the user-key prefix of the supplied

// {MVCC,Engine}Key (the Key field) to restrict which sstables are searched,

// but iteration (using Next) over keys without the same user-key prefix

// will not work correctly (keys may be skipped).

Prefix bool

// LowerBound gives this iterator an inclusive lower bound. Attempts to

// SeekReverse or Prev to a key that is strictly less than the bound will

// invalidate the iterator.

LowerBound roachpb.Key

// UpperBound gives this iterator an exclusive upper bound. Attempts to Seek

// or Next to a key that is greater than or equal to the bound will invalidate

// the iterator. UpperBound must be provided unless Prefix is true, in which

// case the end of the prefix will be used as the upper bound.

UpperBound roachpb.Key

// If WithStats is true, the iterator accumulates performance

// counters over its lifetime which can be queried via `Stats()`.

WithStats bool

// MinTimestampHint and MaxTimestampHint, if set, indicate that keys outside

// of the time range formed by [MinTimestampHint, MaxTimestampHint] do not

// need to be presented by the iterator. The underlying iterator may be able

// to efficiently skip over keys outside of the hinted time range, e.g., when

// an SST indicates that it contains no keys within the time range. Intents

// will not be visible to such iterators at all. This is only relevant for

// MVCCIterators.

//

// Note that time bound hints are strictly a performance optimization, and

// iterators with time bounds hints will frequently return keys outside of the

// [start, end] time range. If you must guarantee that you never see a key

// outside of the time bounds, perform your own filtering.

//

// NB: The iterator may surface stale data. Pebble range tombstones do not have

// timestamps and thus may be ignored entirely depending on whether their SST

// happens to satisfy the filter. Furthermore, keys outside the timestamp

// range may be stale and must be ignored -- for example, consider a key foo@5

// written in an SST with timestamp range [3-7], and then a non-MVCC removal

// or update of this key in a different SST with timestamp range [3-5]. Using

// an iterator with range [6-9] would surface the old foo@5 key because it

// would return all keys in the old [3-7] SST but not take into account the

// separate [3-5] SST where foo@5 was removed or updated. See also:

// https://github.com/cockroachdb/pebble/issues/1786

//

// Currently, the only way to correctly use such an iterator is to use it in

// concert with an iterator without timestamp hints, as done by

// MVCCIncrementalIterator.

MinTimestampHint, MaxTimestampHint hlc.Timestamp

// KeyTypes specifies the types of keys to surface: point and/or range keys.

// Use HasPointAndRange() to determine which key type is present at a given

// iterator position, and RangeBounds() and RangeKeys() to access range keys.

// Defaults to IterKeyTypePointsOnly. For more details on range keys, see

// comment on SimpleMVCCIterator.

KeyTypes IterKeyType

// RangeKeyMaskingBelow enables masking (hiding) of point keys by range keys.

// Any range key with a timestamp at or below RangeKeyMaskingBelow

// will mask point keys below it, preventing them from being surfaced.

// Consider the following example:

//

// 4 o---------------o RangeKeyMaskingBelow=4 emits b3

// 3 b3 d3 RangeKeyMaskingBelow=3 emits b3,d3,f2

// 2 o---------------o f2 RangeKeyMaskingBelow=2 emits b3,d3,f2

// 1 a1 b1 o-------o RangeKeyMaskingBelow=1 emits a1,b3,b1,d3,f2

// a b c d e f g

//

// Range keys themselves are not affected by the masking, and will be

// emitted as normal.

RangeKeyMaskingBelow hlc.Timestamp

// useL6Filters allows the caller to opt into reading filter blocks for

// L6 sstables. Only for use with Prefix = true. Helpful if a lot of prefix

// Seeks are expected in quick succession, that are also likely to not

// yield a single key. Filter blocks in L6 can be relatively large, often

// larger than data blocks, so the benefit of loading them in the cache

// is minimized if the probability of the key existing is not low or if

// this is a one-time Seek (where loading the data block directly is better).

useL6Filters bool

// Close closes the reader, freeing up any outstanding resources. Note that

// various implementations have slightly different behaviors. In particular,

// Distinct() batches release their parent batch for future use while

// Engines, Snapshots and Batches free the associated C++ resources.

Close()

// Closed returns true if the reader has been closed or is not usable.

// Objects backed by this reader (e.g. Iterators) can check this to ensure

// that they are not using a closed engine. Intended for use within package

// engine; exported to enable wrappers to exist in other packages.

Closed() bool

// MVCCGet returns the value for the given key, nil otherwise. Semantically, it

// behaves as if an iterator with MVCCKeyAndIntentsIterKind was used.

//

// Deprecated: use storage.MVCCGet instead.

MVCCGet(key MVCCKey) ([]byte, error)

// MVCCGetProto fetches the value at the specified key and unmarshals it

// using a protobuf decoder. Returns true on success or false if the

// key was not found. On success, returns the length in bytes of the

// key and the value. Semantically, it behaves as if an iterator with

// MVCCKeyAndIntentsIterKind was used.

//

// Deprecated: use MVCCIterator.ValueProto instead.

MVCCGetProto(key MVCCKey, msg protoutil.Message) (ok bool, keyBytes, valBytes int64, err error)

// MVCCIterate scans from the start key to the end key (exclusive), invoking

// the function f on each key value pair. The inputs are copies, and safe to

// retain beyond the function call. It supports interleaved iteration over

// point and/or range keys, providing any overlapping range keys for each

// point key if requested. If f returns an error or if the scan itself

// encounters an error, the iteration will stop and return the error.

//

// Note that this method is not expected take into account the timestamp of

// the end key; all MVCCKeys at end.Key are considered excluded in the

// iteration.

MVCCIterate(start, end roachpb.Key, iterKind MVCCIterKind, keyTypes IterKeyType,

f func(MVCCKeyValue, MVCCRangeKeyStack) error) error

// NewMVCCIterator returns a new instance of an MVCCIterator over this engine.

// The caller must invoke Close() on it when done to free resources.

//

// Write visibility semantics:

//

// 1. An iterator has a consistent view of the reader as of the time of its

// creation. Subsequent writes are never visible to it.

//

// 2. All iterators on readers with ConsistentIterators=true have a consistent

// view of the _engine_ (not reader) as of the time of the first iterator

// creation or PinEngineStateForIterators call: newer engine writes are

// never visible. The opposite holds for ConsistentIterators=false: new

// iterators see the most recent engine state at the time of their creation.

//

// 3. Iterators on unindexed batches never see batch writes, but satisfy

// ConsistentIterators for engine write visibility.

//

// 4. Iterators on indexed batches see all batch writes as of their creation

// time, but they satisfy ConsistentIterators for engine writes.

NewMVCCIterator(iterKind MVCCIterKind, opts IterOptions) MVCCIterator

// NewEngineIterator returns a new instance of an EngineIterator over this

// engine. The caller must invoke EngineIterator.Close() when finished

// with the iterator to free resources. The caller can change IterOptions

// after this function returns.

NewEngineIterator(opts IterOptions) EngineIterator

// ConsistentIterators returns true if the Reader implementation guarantees

// that the different iterators constructed by this Reader will see the same

// underlying Engine state. This is not true about Batch writes: new iterators

// will see new writes made to the batch, existing iterators won't.

ConsistentIterators() bool

// SupportsRangeKeys returns true if the Reader implementation supports

// range keys.

//

// TODO(erikgrinaker): Remove this after 22.2.

SupportsRangeKeys() bool

// PinEngineStateForIterators ensures that the state seen by iterators

// without timestamp hints (see IterOptions) is pinned and will not see

// future mutations. It can be called multiple times on a Reader in which

// case the state seen will be either:

// - As of the first call.

// - For a Reader returned by Engine.NewSnapshot, the pinned state is as of

// the time the snapshot was taken.

// So the semantics that are true for all Readers is that the pinned state

// is somewhere in the time interval between the creation of the Reader and

// the first call to PinEngineStateForIterators.

// REQUIRES: ConsistentIterators returns true.

PinEngineStateForIterators() error

// ApplyBatchRepr atomically applies a set of batched updates. Created by

// calling Repr() on a batch. Using this method is equivalent to constructing

// and committing a batch whose Repr() equals repr. If sync is true, the

// batch is synchronously written to disk. It is an error to specify

// sync=true if the Writer is a Batch.

//

// It is safe to modify the contents of the arguments after ApplyBatchRepr

// returns.

ApplyBatchRepr(repr []byte, sync bool) error

// ClearMVCC removes the point key with the given MVCCKey from the db. It does

// not affect range keys. It requires that the timestamp is non-empty (see

// ClearUnversioned or ClearIntent if the timestamp is empty). Note that clear

// actually removes entries from the storage engine, rather than inserting

// MVCC tombstones.

//

// It is safe to modify the contents of the arguments after it returns.

ClearMVCC(key MVCCKey) error

// ClearUnversioned removes an unversioned item from the db. It is for use

// with inline metadata (not intents) and other unversioned keys (like

// Range-ID local keys). It does not affect range keys.

//

// It is safe to modify the contents of the arguments after it returns.

ClearUnversioned(key roachpb.Key) error

// ClearIntent removes an intent from the db. Unlike ClearMVCC and

// ClearUnversioned, this is a higher-level method that may make changes in

// parts of the key space that are not only a function of the input, and may

// choose to use a single-clear under the covers. txnDidNotUpdateMeta allows

// for performance optimization when set to true, and has semantics defined in

// MVCCMetadata.TxnDidNotUpdateMeta (it can be conservatively set to false).

//

// It is safe to modify the contents of the arguments after it returns.

//

// TODO(sumeer): after the full transition to separated locks, measure the

// cost of a PutIntent implementation, where there is an existing intent,

// that does a <single-clear, put> pair. If there isn't a performance

// decrease, we can stop tracking txnDidNotUpdateMeta and still optimize

// ClearIntent by always doing single-clear.

ClearIntent(key roachpb.Key, txnDidNotUpdateMeta bool, txnUUID uuid.UUID) error

// ClearEngineKey removes the given point key from the engine. It does not

// affect range keys. Note that clear actually removes entries from the

// storage engine. This is a general-purpose and low-level method that should

// be used sparingly, only when the other Clear* methods are not applicable.

//

// It is safe to modify the contents of the arguments after it returns.

ClearEngineKey(key EngineKey) error

// ClearRawRange removes point and/or range keys from start (inclusive) to end

// (exclusive) using Pebble range tombstones. It can be applied to a range

// consisting of MVCCKeys or the more general EngineKeys -- it simply uses the

// roachpb.Key parameters as the Key field of an EngineKey. This implies that

// it does not clear intents unless the intent lock table is targeted

// explicitly.

//

// Similar to the other Clear* methods, this method actually removes entries

// from the storage engine. It is safe to modify the contents of the arguments

// after it returns.

ClearRawRange(start, end roachpb.Key, pointKeys, rangeKeys bool) error

// ClearMVCCRange removes MVCC point and/or range keys (including intents)

// from start (inclusive) to end (exclusive) using Pebble range tombstones.

//

// Similar to the other Clear* methods, this method actually removes entries

// from the storage engine. It is safe to modify the contents of the arguments

// after it returns.

ClearMVCCRange(start, end roachpb.Key, pointKeys, rangeKeys bool) error

// ClearMVCCVersions removes MVCC point key versions from start (inclusive) to

// end (exclusive) using a Pebble range tombstone. It is meant for efficiently

// clearing a subset of versions of a key, since the parameters are MVCCKeys

// and not roachpb.Keys, but it can also be used across multiple keys. It will

// ignore intents and range keys, leaving them in place.

//

// Similar to the other Clear* methods, this method actually removes entries

// from the storage engine. It is safe to modify the contents of the arguments

// after it returns.

ClearMVCCVersions(start, end MVCCKey) error

// ClearMVCCIteratorRange removes all point and/or range keys in the given

// span using an MVCC iterator, by clearing individual keys (including

// intents).

//

// Similar to the other Clear* methods, this method actually removes entries

// from the storage engine. It is safe to modify the contents of the arguments

// after it returns.

//

// TODO(erikgrinaker): This should be a separate function rather than an

// interface method, but we keep it for now to make use of UnsafeRawKey() when

// clearing keys.

ClearMVCCIteratorRange(start, end roachpb.Key, pointKeys, rangeKeys bool) error

// ClearMVCCRangeKey deletes an MVCC range key from start (inclusive) to end

// (exclusive) at the given timestamp. For any range key that straddles the

// start and end boundaries, only the segments within the boundaries will be

// cleared. Range keys at other timestamps are unaffected. Clears are

// idempotent.

//

// This method is primarily intended for MVCC garbage collection and similar

// internal use.

ClearMVCCRangeKey(rangeKey MVCCRangeKey) error

// PutMVCCRangeKey writes an MVCC range key. It will replace any overlapping

// range keys at the given timestamp (even partial overlap). Only MVCC range

// tombstones, i.e. an empty value, are currently allowed (other kinds will

// need additional handling in MVCC APIs and elsewhere, e.g. stats and GC).

//

// Range keys must be accessed using special iterator options and methods,

// see SimpleMVCCIterator.RangeKeys() for details.

//

// For more information on MVCC range keys, see this tech note:

// https://github.com/cockroachdb/cockroach/blob/master/docs/tech-notes/mvcc-range-tombstones.md

PutMVCCRangeKey(MVCCRangeKey, MVCCValue) error

// PutRawMVCCRangeKey is like PutMVCCRangeKey, but accepts an encoded

// MVCCValue. It can be used to avoid decoding and immediately re-encoding an

// MVCCValue, but should generally be avoided due to the lack of type safety.

//

// It is safe to modify the contents of the arguments after PutRawMVCCRangeKey

// returns.

PutRawMVCCRangeKey(MVCCRangeKey, []byte) error

// PutEngineRangeKey sets the given range key to the values provided. This is

// a general-purpose and low-level method that should be used sparingly, only

// when the other Put* methods are not applicable.

//

// It is safe to modify the contents of the arguments after it returns.

PutEngineRangeKey(start, end roachpb.Key, suffix, value []byte) error

// ClearEngineRangeKey clears the given range key. This is a general-purpose

// and low-level method that should be used sparingly, only when the other

// Clear* methods are not applicable.

//

// It is safe to modify the contents of the arguments after it returns.

ClearEngineRangeKey(start, end roachpb.Key, suffix []byte) error

// Merge is a high-performance write operation used for values which are

// accumulated over several writes. Multiple values can be merged

// sequentially into a single key; a subsequent read will return a "merged"

// value which is computed from the original merged values. We only

// support Merge for keys with no version.

//

// Merge currently provides specialized behavior for three data types:

// integers, byte slices, and time series observations. Merged integers are

// summed, acting as a high-performance accumulator. Byte slices are simply

// concatenated in the order they are merged. Time series observations

// (stored as byte slices with a special tag on the roachpb.Value) are

// combined with specialized logic beyond that of simple byte slices.

//

//

// It is safe to modify the contents of the arguments after Merge returns.

Merge(key MVCCKey, value []byte) error

// PutMVCC sets the given key to the value provided. It requires that the

// timestamp is non-empty (see {PutUnversioned,PutIntent} if the timestamp

// is empty).

//

// It is safe to modify the contents of the arguments after PutMVCC returns.

PutMVCC(key MVCCKey, value MVCCValue) error

// PutRawMVCC is like PutMVCC, but it accepts an encoded MVCCValue. It

// can be used to avoid decoding and immediately re-encoding an MVCCValue,

// but should generally be avoided due to the lack of type safety.

//

// It is safe to modify the contents of the arguments after PutRawMVCC

// returns.

PutRawMVCC(key MVCCKey, value []byte) error

// PutUnversioned sets the given key to the value provided. It is for use

// with inline metadata (not intents) and other unversioned keys (like

// Range-ID local keys).

//

// It is safe to modify the contents of the arguments after Put returns.

PutUnversioned(key roachpb.Key, value []byte) error

// PutIntent puts an intent at the given key to the value provided. This is

// a higher-level method that may make changes in parts of the key space

// that are not only a function of the input key, and may explicitly clear

// the preceding intent. txnDidNotUpdateMeta defines what happened prior to

// this put, and allows for performance optimization when set to true, and

// has semantics defined in MVCCMetadata.TxnDidNotUpdateMeta (it can be

// conservatively set to false).

//

// It is safe to modify the contents of the arguments after Put returns.

PutIntent(ctx context.Context, key roachpb.Key, value []byte, txnUUID uuid.UUID) error

// PutEngineKey sets the given key to the value provided. This is a

// general-purpose and low-level method that should be used sparingly,

// only when the other Put* methods are not applicable.

//

// It is safe to modify the contents of the arguments after Put returns.

PutEngineKey(key EngineKey, value []byte) error

// LogData adds the specified data to the RocksDB WAL. The data is

// uninterpreted by RocksDB (i.e. not added to the memtable or sstables).

//

// It is safe to modify the contents of the arguments after LogData returns.

LogData(data []byte) error

// LogLogicalOp logs the specified logical mvcc operation with the provided

// details to the writer, if it has logical op logging enabled. For most

// Writer implementations, this is a no-op.

LogLogicalOp(op MVCCLogicalOpType, details MVCCLogicalOpDetails)

// SingleClearEngineKey removes the most recent write to the item from the db

// with the given key. Whether older writes of the item will come back

// to life if not also removed with SingleClear is undefined. See the

// following:

// https://github.com/facebook/rocksdb/wiki/Single-Delete

// for details on the SingleDelete operation that this method invokes. Note

// that clear actually removes entries from the storage engine, rather than

// inserting MVCC tombstones. This is a low-level interface that must not be

// called from outside the storage package. It is part of the interface

// because there are structs that wrap Writer and implement the Writer

// interface, that are not part of the storage package.

//

// It is safe to modify the contents of the arguments after it returns.

SingleClearEngineKey(key EngineKey) error

// ShouldWriteLocalTimestamps is only for internal use in the storage package.

// This method is temporary, to handle the transition from clusters where not

// all nodes understand local timestamps.

ShouldWriteLocalTimestamps(ctx context.Context) bool

ReadWriter

// Attrs returns the engine/store attributes.

Attrs() roachpb.Attributes

// Capacity returns capacity details for the engine's available storage.

Capacity() (roachpb.StoreCapacity, error)

// Properties returns the low-level properties for the engine's underlying storage.

Properties() roachpb.StoreProperties

// Compact forces compaction over the entire database.

Compact() error

// Flush causes the engine to write all in-memory data to disk

// immediately.

Flush() error

// GetMetrics retrieves metrics from the engine.

GetMetrics() Metrics

// GetEncryptionRegistries returns the file and key registries when encryption is enabled

// on the store.

GetEncryptionRegistries() (*EncryptionRegistries, error)

// GetEnvStats retrieves stats about the engine's environment

// For RocksDB, this includes details of at-rest encryption.

GetEnvStats() (*EnvStats, error)

// GetAuxiliaryDir returns a path under which files can be stored

// persistently, and from which data can be ingested by the engine.

//

// Not thread safe.

GetAuxiliaryDir() string

// NewBatch returns a new instance of a batched engine which wraps

// this engine. Batched engines accumulate all mutations and apply

// them atomically on a call to Commit().

NewBatch() Batch

// NewReadOnly returns a new instance of a ReadWriter that wraps this

// engine, and with the given durability requirement. This wrapper panics

// when unexpected operations (e.g., write operations) are executed on it

// and caches iterators to avoid the overhead of creating multiple iterators

// for batched reads.

//

// All iterators created from a read-only engine are guaranteed to provide a

// consistent snapshot of the underlying engine. See the comment on the

// Reader interface and the Reader.ConsistentIterators method.

NewReadOnly(durability DurabilityRequirement) ReadWriter

// NewUnindexedBatch returns a new instance of a batched engine which wraps

// this engine. It is unindexed, in that writes to the batch are not

// visible to reads until after it commits. The batch accumulates all

// mutations and applies them atomically on a call to Commit(). Read

// operations return an error, unless writeOnly is set to false.

//

// When writeOnly is false, reads will be satisfied by reading from the

// underlying engine, i.e., the caller does not see its own writes. This

// setting should be used only when the caller is certain that this

// optimization is correct, and beneficial. There are subtleties here -- see

// the discussion on https://github.com/cockroachdb/cockroach/pull/57661 for

// more details.

//

// TODO(sumeer): We should separate the writeOnly=true case into a

// separate method, that returns a WriteBatch interface. Even better would

// be not having an option to pass writeOnly=false, and have the caller

// explicitly work with a separate WriteBatch and Reader.

NewUnindexedBatch(writeOnly bool) Batch

// NewSnapshot returns a new instance of a read-only snapshot

// engine. Snapshots are instantaneous and, as long as they're

// released relatively quickly, inexpensive. Snapshots are released

// by invoking Close(). Note that snapshots must not be used after the

// original engine has been stopped.

NewSnapshot() Reader

// Type returns engine type.

Type() enginepb.EngineType

// IngestExternalFiles atomically links a slice of files into the RocksDB

// log-structured merge-tree.

IngestExternalFiles(ctx context.Context, paths []string) error

// PreIngestDelay offers an engine the chance to backpressure ingestions.

// When called, it may choose to block if the engine determines that it is in

// or approaching a state where further ingestions may risk its health.

PreIngestDelay(ctx context.Context)

// ApproximateDiskBytes returns an approximation of the on-disk size for the given key span.

ApproximateDiskBytes(from, to roachpb.Key) (uint64, error)

// CompactRange ensures that the specified range of key value pairs is

// optimized for space efficiency.

CompactRange(start, end roachpb.Key) error

// InMem returns true if the receiver is an in-memory engine and false

// otherwise.

//

// TODO(peter): This is a bit of a wart in the interface. It is used by

// addSSTablePreApply to select alternate code paths, but really there should

// be a unified code path there.

InMem() bool

// RegisterFlushCompletedCallback registers a callback that will be run for

// every successful flush. Only one callback can be registered at a time, so

// registering again replaces the previous callback. The callback must

// return quickly and must not call any methods on the Engine in the context

// of the callback since it could cause a deadlock (since the callback may

// be invoked while holding mutexes).

RegisterFlushCompletedCallback(cb func())

// Filesystem functionality.

fs.FS

// ReadFile reads the content from the file with the given filename int this RocksDB's env.

ReadFile(filename string) ([]byte, error)

// WriteFile writes data to a file in this RocksDB's env.

WriteFile(filename string, data []byte) error

// CreateCheckpoint creates a checkpoint of the engine in the given directory,

// which must not exist. The directory should be on the same file system so

// that hard links can be used.

CreateCheckpoint(dir string) error

// SetMinVersion is used to signal to the engine the current minimum

// version that it must maintain compatibility with.

SetMinVersion(version roachpb.Version) error

// MinVersionIsAtLeastTargetVersion returns whether the engine's recorded

// storage min version is at least the target version.

MinVersionIsAtLeastTargetVersion(target roachpb.Version) (bool, error)

// GetInternalIntervalMetrics returns low-level metrics from Pebble, that

// are reset at every interval, where an interval is defined over successive

// calls to this method. Hence, this should be used with care, with only one

// caller, which is currently the admission control subsystem.

GetInternalIntervalMetrics() *pebble.InternalIntervalMetrics

// Iterators created on a batch can see some mutations performed after the

// iterator creation. To guarantee that they see all the mutations, the

// iterator has to be repositioned using a seek operation, after the

// mutations were done.

ReadWriter

// Commit atomically applies any batched updates to the underlying

// engine. This is a noop unless the batch was created via NewBatch(). If

// sync is true, the batch is synchronously committed to disk.

Commit(sync bool) error

// Empty returns whether the batch has been written to or not.

Empty() bool

// Count returns the number of memtable-modifying operations in the batch.

Count() uint32

// Len returns the size of the underlying representation of the batch.

// Because of the batch header, the size of the batch is never 0 and should

// not be used interchangeably with Empty. The method avoids the memory copy

// that Repr imposes, but it still may require flushing the batch's mutations.

Len() int

// Repr returns the underlying representation of the batch and can be used to

// reconstitute the batch on a remote node using Writer.ApplyBatchRepr().

Repr() []byte

*pebble.Metrics

// WriteStallCount counts the number of times Pebble intentionally delayed

// incoming writes. Currently, the only two reasons for this to happen are:

// - "memtable count limit reached"

// - "L0 file count limit exceeded"

//

// We do not split this metric across these two reasons, but they can be

// distinguished in the pebble logs.

WriteStallCount int64

WriteStallDuration time.Duration

// DiskSlowCount counts the number of times Pebble records disk slowness.

DiskSlowCount int64

// DiskStallCount counts the number of times Pebble observes slow writes

// on disk lasting longer than MaxSyncDuration (`storage.max_sync_duration`).

DiskStallCount int64