cockroach: Index | Files | Directories

package protectedts

import ""

Package protectedts exports the interface to the protected timestamp subsystem which allows clients to prevent GC of expired data.


Package Files

protectedts.go settings.go


var ErrExists = errors.New("protected timestamp record already exists")

ErrExists returned from Protect when trying to protect a record with an ID which already exists.

var ErrNotExists = errors.New("protected timestamp record does not exist")

ErrNotExists is returned from Get or Release if the record does not exist.

var MaxBytes = settings.RegisterNonNegativeIntSetting(
    "if non-zero the limit of the number of bytes of spans and metadata which can be protected",

MaxBytes controls the maximum number of bytes worth of spans and metadata which can be protected by all protected timestamp records.

var MaxSpans = settings.RegisterNonNegativeIntSetting(
    "if non-zero the limit of the number of spans which can be protected",

MaxSpans controls the maximum number of spans which can be protected by all protected timestamp records.

var PollInterval = settings.RegisterNonNegativeDurationSetting(

    "the interval at which the protectedts subsystem state is polled",

PollInterval defines how frequently the protectedts state is polled by the Tracker.

type Cache Uses

type Cache interface {

    // Iterate examines the records with spans which overlap with [from, to).
    // Nil values for from or to are equivalent to Key{}. The order of records
    // between independent calls to Iterate is not defined; the order of records
    // may differ even for the same key range that occurs at the same timestamp.
    // The Records passed to the iterator are safe to be retained but must not be
    // modified.
    Iterate(_ context.Context, from, to roachpb.Key, it Iterator) (asOf hlc.Timestamp)

    // QueryRecord determines whether a Record with the provided ID exists in
    // the Cache state and returns the timestamp corresponding to that state.
    QueryRecord(_ context.Context, id uuid.UUID) (exists bool, asOf hlc.Timestamp)

    // Refresh forces the cache to update to at least asOf.
    Refresh(_ context.Context, asOf hlc.Timestamp) error

Cache is used in the storage package to determine a safe timestamp for garbage collection of expired data. A storage.Replica can remove data when it has a proof from the Cache that there was no Record providing protection. For example, a Replica which determines that it is not protected by any Records at a given asOf can move its GC threshold up to that timestamp less its GC TTL.

func EmptyCache Uses

func EmptyCache(c *hlc.Clock) Cache

EmptyCache returns a Cache which always returns the current time and no records. This is often useful in testing where you want a cache which holds nothing and is always up-to-date.

type Iterator Uses

type Iterator func(*ptpb.Record) (wantMore bool)

Iterator iterates records in a cache until wantMore is false or all Records in the requested range have been seen.

type Provider Uses

type Provider interface {

    Start(context.Context, *stop.Stopper) error

Provider is the central coordinator for the protectedts subsystem. It exists to abstract interaction with subsystem.

type Storage Uses

type Storage interface {

    // Protect will durably create a protected timestamp, if no error is returned
    // then no data in the specified spans which are live at the specified
    // timestamp can be garbage collected until this Record is released.
    // Protect may succeed and yet data may be or already have been garbage
    // collected in the spans specified by the Record. However, the protected
    // timestamp subsystem guarantees that if all possible zone configs which
    // could have applied have GC TTLs which would not have allowed data at
    // the timestamp which the passed Txn commits to be GC'd then that
    // data will not be GC'd until this *Record is released.
    // An error will be returned if the ID of the provided record already exists
    // so callers should be sure to generate new IDs when creating records.
    Protect(context.Context, *kv.Txn, *ptpb.Record) error

    // GetRecord retreives the record with the specified UUID as well as the MVCC
    // timestamp at which it was written. If no corresponding record exists
    // ErrNotExists is returned.
    // GetRecord exists to work in coordination with verification. In order
    // to use Verifier.Verify a client must provide both the timestamp which
    // should be protected as well as the timestamp at which the Record providing
    // that protection is known to be alive. The ReadTimestamp of the Txn used in
    // this method can be used to provide such a timestamp.
    GetRecord(context.Context, *kv.Txn, uuid.UUID) (*ptpb.Record, error)

    // MarkVerified will mark a protected timestamp as verified.
    // This method is generally used by an implementation of Verifier.
    MarkVerified(context.Context, *kv.Txn, uuid.UUID) error

    // Release allows spans which were previously protected to now be garbage
    // collected.
    // If the specified UUID does not exist ErrNotFound is returned but the
    // passed txn remains safe for future use.
    Release(context.Context, *kv.Txn, uuid.UUID) error

    // GetMetadata retreives the metadata with the provided Txn.
    GetMetadata(context.Context, *kv.Txn) (ptpb.Metadata, error)

    // GetState retreives the entire state of protectedts.Storage with the
    // provided Txn.
    GetState(context.Context, *kv.Txn) (ptpb.State, error)

Storage provides clients with a mechanism to transactionally protect and release protected timestamps for a set of spans.

Clients may provide a txn object which will allow them to write the id of this new protection transactionally into their own state. It is the caller's responsibility to ensure that a timestamp is ultimately released.

type Verifier Uses

type Verifier interface {

    // Verify returns an error if the record of the provided ID cannot be
    // verified. If nil is returned then the record has been proven to apply
    // until it is removed.
    Verify(context.Context, uuid.UUID) error

Verifier provides a mechanism to verify that a created Record will certainly apply.


ptproviderPackage ptprovider encapsulates the concrete implementation of the protectedts.Provider.
ptreconcilePackage ptreconcile provides logic to reconcile protected timestamp records with state associated with their metadata.
ptstoragePackage ptstorage implements protectedts.Storage.

Package protectedts imports 10 packages (graph) and is imported by 28 packages. Updated 2020-08-12. Refresh now. Tools for package owners.