cockroach: Index | Files

package clusterversion

import ""

Package clusterversion defines the interfaces to interact with cluster/binary versions in order accommodate backward incompatible behaviors. It handles the feature gates and so must maintain a fairly lightweight set of dependencies. The migration sub-package will handle advancing a cluster from one version to a later one.

Ideally, every code change in a database would be backward compatible, but this is not always possible. Some features, fixes, or cleanups need to introduce a backward incompatibility and others are dramatically simplified by it. This package provides a way to do this safely with (hopefully) minimal disruption. It works as follows:

- Each node in the cluster is running a binary that was released at some

version ("binary version"). We allow for rolling upgrades, so two nodes in
the cluster may be running different binary versions. All nodes in a given
cluster must be within 1 major release of each other (i.e. to upgrade two
major releases, the cluster must first be rolled onto X+1 and then to X+2).

- Separate from the build versions of the binaries, the cluster itself has a

logical "active cluster version", the version all the binaries are
currently operating at. This is used for two related things: first as a
promise from the user that they'll never downgrade any nodes in the cluster
to a binary below some "minimum supported version", and second, to unlock
features that are not backwards compatible (which is now safe given that
the old binary will never be used).

- Each binary can operate within a "range of supported versions". When a

cluster is initialized, the binary doing the initialization uses the upper
end of its supported range as the initial "active cluster version". Each
node that joins this cluster then must be compatible with this cluster


Package Files

cluster_version.pb.go clusterversion.go cockroach_versions.go keyed_versions.go setting.go testutils.go versionkey_string.go


const KeyVersionSetting = "version"

KeyVersionSetting is the "version" settings key.


var (
    ErrInvalidLengthClusterVersion = fmt.Errorf("proto: negative length found during unmarshaling")
    ErrIntOverflowClusterVersion   = fmt.Errorf("proto: integer overflow")
var TestingBinaryMinSupportedVersion = binaryMinSupportedVersion

TestingBinaryMinSupportedVersion is a minimum supported version that tests can use when they don't want to go through a Settings object.

var TestingBinaryVersion = binaryVersion

TestingBinaryVersion is a binary version that tests can use when they don't want to go through a Settings object.

var TestingClusterVersion = ClusterVersion{
    Version: TestingBinaryVersion,

TestingClusterVersion is a ClusterVersion that tests can use when they don't want to go through a Settings object.

func Initialize Uses

func Initialize(ctx context.Context, ver roachpb.Version, sv *settings.Values) error

Initialize initializes the global cluster version. Before this method has been called, usage of the cluster version (through Handle) is illegal and leads to a fatal error.

func SetBeforeChange Uses

func SetBeforeChange(
    ctx context.Context, sv *settings.Values, cb func(context.Context, ClusterVersion),

SetBeforeChange registers a callback to be called before the global cluster version is updated. The new cluster version will only become "visible" after the callback has returned.

The callback can be set at most once.

func VersionByKey Uses

func VersionByKey(key VersionKey) roachpb.Version

VersionByKey returns the roachpb.Version for a given key. It is a fatal error to use an invalid key.

type ClusterVersion Uses

type ClusterVersion struct {
    // The version of functionality in use in the cluster. This value must
    // monotonically increase.
    roachpb.Version `protobuf:"bytes,2,opt,name=active_version,json=activeVersion,proto3,embedded=active_version" json:"active_version"`

ClusterVersion represents a cluster's "active version". It is returned by the Version cluster setting. Its IsActive() method can be used to determine if a particular migration is to be considered enabled or disabled.

func (*ClusterVersion) Descriptor Uses

func (*ClusterVersion) Descriptor() ([]byte, []int)

func (ClusterVersion) IsActive Uses

func (cv ClusterVersion) IsActive(versionKey VersionKey) bool

IsActive returns true if the features of the supplied version are active at the running version.

func (ClusterVersion) IsActiveVersion Uses

func (cv ClusterVersion) IsActiveVersion(v roachpb.Version) bool

IsActiveVersion returns true if the features of the supplied version are active at the running version.

func (*ClusterVersion) Marshal Uses

func (m *ClusterVersion) Marshal() (dAtA []byte, err error)

func (*ClusterVersion) MarshalTo Uses

func (m *ClusterVersion) MarshalTo(dAtA []byte) (int, error)

func (*ClusterVersion) ProtoMessage Uses

func (*ClusterVersion) ProtoMessage()

func (*ClusterVersion) Reset Uses

func (m *ClusterVersion) Reset()

func (*ClusterVersion) Size Uses

func (m *ClusterVersion) Size() (n int)

func (ClusterVersion) String Uses

func (cv ClusterVersion) String() string

func (*ClusterVersion) Unmarshal Uses

func (m *ClusterVersion) Unmarshal(dAtA []byte) error

func (*ClusterVersion) XXX_DiscardUnknown Uses

func (m *ClusterVersion) XXX_DiscardUnknown()

func (*ClusterVersion) XXX_Marshal Uses

func (m *ClusterVersion) XXX_Marshal(b []byte, deterministic bool) ([]byte, error)

func (*ClusterVersion) XXX_Merge Uses

func (dst *ClusterVersion) XXX_Merge(src proto.Message)

func (*ClusterVersion) XXX_Size Uses

func (m *ClusterVersion) XXX_Size() int

func (*ClusterVersion) XXX_Unmarshal Uses

func (m *ClusterVersion) XXX_Unmarshal(b []byte) error

type Handle Uses

type Handle interface {
    // ActiveVersion returns the cluster's current active version: the minimum
    // cluster version the caller may assume is in effect.
    // ActiveVersion fatals if the cluster version setting has not been
    // initialized (through `Initialize()`).
    ActiveVersion(context.Context) ClusterVersion

    // ActiveVersionOrEmpty is like ActiveVersion, but returns an empty version
    // if the active version was not initialized.
    ActiveVersionOrEmpty(context.Context) ClusterVersion

    // IsActive returns true if the features of the supplied version key are
    // active at the running version. In other words, if a particular version
    // `v` returns true from this method, it means that you're guaranteed that
    // all of the nodes in the cluster have running binaries that are at least
    // as new as `v`, and that those nodes will never be downgraded to a binary
    // with a version less than `v`.
    // If this returns true then all nodes in the cluster will eventually see
    // this version. However, this is not atomic because versions are gossiped.
    // Because of this, nodes should not be gating proper handling of remotely
    // initiated requests that their binary knows how to handle on this state.
    // The following example shows why this is important:
    //  The cluster restarts into the new version and the operator issues a SET
    //  VERSION, but node1 learns of the bump 10 seconds before node2, so during
    //  that window node1 might be receiving "old" requests that it itself
    //  wouldn't issue any more. Similarly, node2 might be receiving "new"
    //  requests that its binary must necessarily be able to handle (because the
    //  SET VERSION was successful) but that it itself wouldn't issue yet.
    // This is still a useful method to have as node1, in the example above, can
    // use this information to know when it's safe to start issuing "new"
    // outbound requests. When receiving these "new" inbound requests, despite
    // not seeing the latest active version, node2 is aware that the sending
    // node has, and it will too, eventually.
    IsActive(context.Context, VersionKey) bool

    // BinaryVersion returns the build version of this binary.
    BinaryVersion() roachpb.Version

    // BinaryMinSupportedVersion returns the earliest binary version that can
    // interoperate with this binary.
    BinaryMinSupportedVersion() roachpb.Version

Handle is a read-only view to the active cluster version and this binary's version details.

func MakeVersionHandle Uses

func MakeVersionHandle(sv *settings.Values) Handle

MakeVersionHandle returns a Handle that has its binary and minimum supported versions initialized to this binary's build and it's minimum supported versions respectively.

func MakeVersionHandleWithOverride Uses

func MakeVersionHandleWithOverride(
    sv *settings.Values, binaryVersion, binaryMinSupportedVersion roachpb.Version,
) Handle

MakeVersionHandleWithOverride returns a Handle that has its binary and minimum supported versions initialized to the provided versions.

It's typically used in tests that want to override the default binary and minimum supported versions.

type VersionKey Uses

type VersionKey int

VersionKey is a unique identifier for a version of CockroachDB.

const (
    Version19_1 VersionKey

Version constants.

To add a version:

- Add it at the end of this block.
- Add it at the end of the `Versions` block below.
- For major or minor versions, bump binaryMinSupportedVersion. For
  example, if introducing the `20.1` release, bump it to
  VersionStart19_2 (i.e. `19.1-1`).

To delete a version.

- Remove its associated runtime checks.
- If the version is not the latest one, delete the constant, comment out
  its stanza, and say "Removed." above the versionsSingleton.

go:generate stringer -type=VersionKey

func (VersionKey) String Uses

func (i VersionKey) String() string

Package clusterversion imports 14 packages (graph) and is imported by 42 packages. Updated 2020-08-12. Refresh now. Tools for package owners.