cockroach: Index | Files

package cluster

import ""


Package Files

cluster_version.go cluster_version.pb.go cockroach_versions.go keyed_versions.go settings.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 (
    // BinaryMinimumSupportedVersion is the earliest version of data supported by
    // this binary. If this binary is started using a store marked with an older
    // version than BinaryMinimumSupportedVersion, then the binary will exit with
    // an error.
    BinaryMinimumSupportedVersion = VersionByKey(Version19_1)

    // BinaryServerVersion is the version of this binary.
    // This is the version that a new cluster will use when created.
    BinaryServerVersion = versionsSingleton[len(versionsSingleton)-1].Version

func TelemetryOptOut Uses

func TelemetryOptOut() bool

TelemetryOptOut is a place for controlling whether to opt out of telemetry or not.

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"`
var TestingClusterVersion ClusterVersion = ClusterVersion{
    Version: BinaryServerVersion,

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

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 (m *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 ExposedClusterVersion Uses

type ExposedClusterVersion struct {
    MinSupportedVersion roachpb.Version
    ServerVersion       roachpb.Version
    // contains filtered or unexported fields

An ExposedClusterVersion exposes a cluster-wide minimum version which is assumed to be supported by all nodes. This in turn allows features which are incompatible with older versions to be used safely.

func (*ExposedClusterVersion) BootstrapVersion Uses

func (ecv *ExposedClusterVersion) BootstrapVersion() ClusterVersion

BootstrapVersion returns the version a newly initialized cluster should have.

func (*ExposedClusterVersion) CheckVersion Uses

func (ecv *ExposedClusterVersion) CheckVersion(versionKey VersionKey, feature string) error

CheckVersion is like IsActive but returns an appropriate error in the case of a cluster version which is too low.

func (*ExposedClusterVersion) IsActive Uses

func (ecv *ExposedClusterVersion) IsActive(versionKey VersionKey) bool

IsActive returns true if the features of the supplied version key are active at the running version. In other words, if a particular version 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 that version, and that you're guaranteed that those nodes will never be downgraded to an older version.

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 gate 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.

func (*ExposedClusterVersion) IsInitialized Uses

func (ecv *ExposedClusterVersion) IsInitialized() bool

IsInitialized returns true if the cluster version has been initialized and is ready for use.

func (*ExposedClusterVersion) OnChange Uses

func (ecv *ExposedClusterVersion) OnChange(f func(cv ClusterVersion))

OnChange registers (a single) callback that will be invoked whenever the cluster version changes. The new cluster version will only become "visible" after the callback has returned.

The callback can be set at most once.

func (*ExposedClusterVersion) Version Uses

func (ecv *ExposedClusterVersion) Version() ClusterVersion

Version returns the minimum cluster version the caller may assume is in effect. It must not be called until the setting has been initialized.

type Settings Uses

type Settings struct {
    SV  settings.Values

    // Manual defaults to false. If set, lets this ClusterSetting's MakeUpdater
    // method return a dummy updater that simply throws away all values. This is
    // for use in tests for which manual control is desired.
    // Also see the Override() method that different types of settings provide for
    // overwriting the default of a single setting.
    Manual atomic.Value // bool

    Version ExposedClusterVersion

    Tracer        *tracing.Tracer
    ExternalIODir string

    Initialized bool
    // contains filtered or unexported fields

Settings is the collection of cluster settings. For a running CockroachDB node, there is a single instance of ClusterSetting which is shared across all of its components.

The Version setting deserves an individual explanantion. During the node startup sequence, an initial version (persisted to the engines) is read and passed to InitializeVersion(). It is only after that that the Version field of this struct is ready for use (i.e. Version() and IsActive() can be called). In turn, the node usually registers itself as a callback to be notified of any further updates to the setting, which are then persisted.

This dance is necessary because we cannot determine a safe default value for the version setting without looking at what's been persisted: The setting specifies the minimum binary version we have to expect to be in a mixed cluster with. We can't assume this binary's MinimumSupportedVersion as we could've started up earlier and enabled features that are not actually compatible with that version; we can't assume it's our binary's ServerVersion as that would enable features that may trip up older versions running in the same cluster. Hence, only once we get word of the "safe" version to use can we allow moving parts that actually need to know what's going on.

Additionally, whenever the version changes, we want to persist that update to wherever the caller to InitializeVersion() got the initial version from (typically a collection of `engine.Engine`s), which the caller will do by registering itself via `(*Setting).Version.OnChange()`, which is invoked *before* exposing the new version to callers of `IsActive()` and `Version()`.

For testing or one-off situations in which a ClusterSetting is needed, but cluster settings don't play a crucial role, MakeTestingClusterSetting() is provided; it is pre-initialized to the binary's ServerVersion.

var NoSettings *Settings // = nil

NoSettings is used when a func requires a Settings but none is available (for example, a CLI subcommand that does not connect to a cluster).

func MakeClusterSettings Uses

func MakeClusterSettings(minVersion, serverVersion roachpb.Version) *Settings

MakeClusterSettings makes a new ClusterSettings object for the given minimum supported and server version, respectively.

func MakeTestingClusterSettings Uses

func MakeTestingClusterSettings() *Settings

MakeTestingClusterSettings returns a Settings object that has had its version initialized to BinaryServerVersion.

func MakeTestingClusterSettingsWithVersion Uses

func MakeTestingClusterSettingsWithVersion(minVersion, serverVersion roachpb.Version) *Settings

MakeTestingClusterSettingsWithVersion returns a Settings object that has had its version initialized to the provided version configuration.

func (*Settings) InitializeVersion Uses

func (s *Settings) InitializeVersion(cv ClusterVersion) error

InitializeVersion initializes the Version field of this setting. Before this method has been called, usage of the Version field is illegal and leads to a fatal error.

func (*Settings) IsCPUProfiling Uses

func (s *Settings) IsCPUProfiling() bool

IsCPUProfiling returns true if a pprofui CPU profile is being recorded. This can be used by moving parts across the system to add profiler labels which are too expensive to be enabled at all times.

func (*Settings) MakeUpdater Uses

func (s *Settings) MakeUpdater() settings.Updater

MakeUpdater returns a new Updater, pre-alloced to the registry size. Note that if the Setting has the Manual flag set, this Updater simply ignores all updates.

func (*Settings) SetCPUProfiling Uses

func (s *Settings) SetCPUProfiling(to bool)

SetCPUProfiling is called from the pprofui to inform the system that a CPU profile is being recorded.

type VersionKey Uses

type VersionKey int

VersionKey is a unique identifier for a version of CockroachDB.

const (
    Version2_1                            VersionKey
    VersionUnreplicatedRaftTruncatedState // see versionsSingleton for details
    VersionSideloadedStorageNoReplicaID   // see versionsSingleton for details

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 BinaryMinimumSupportedVersion. For
  example, if introducing the `1.4` release, bump it from `1.2` to `1.3`.

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 cluster imports 18 packages (graph) and is imported by 89 packages. Updated 2019-09-19. Refresh now. Tools for package owners.