cockroach: github.com/cockroachdb/cockroach/pkg/settings/cluster Index | Files

package cluster

import "github.com/cockroachdb/cockroach/pkg/settings/cluster"

Index

Package Files

cluster_version.go cluster_version.pb.go cockroach_versions.go keyed_versions.go settings.go testutils.go versionkey_string.go

Constants

const KeyVersionSetting = "version"

KeyVersionSetting is the "version" settings key.

Variables

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.
    // We support everything after 19.1, including pre-release 19.2 versions.
    // This is generally beneficial, but in particular it allows the
    // version-upgrade roachtest to use a pre-release 19.2 binary before upgrading
    // to HEAD; if we were to set BinaryMinimumSupportedVersion to Version19_2,
    // that wouldn't work since you'd have to go through the final 19.2 binary
    // before going to HEAD.
    BinaryMinimumSupportedVersion = VersionByKey(VersionStart19_2)

    // 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
)
var Version = registerClusterVersionSetting()

Version represents the cluster's "active version". The active version is a cluster setting, but a special one. It can only advance to higher and higher versions. The setting can be used to see if migrations are to be considered enabled or disabled through the IsActive() method.

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 Initialize() got the initial version from (typically a collection of `engine.Engine`s), which the caller will do by registering itself via SetBeforeChange()`, which is invoked *before* exposing the new version to callers of `IsActive()` and `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"`
}

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.

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 (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 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

    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.

For testing or one-off situations in which a ClusterSetting is needed, but cluster settings don't play a crucial role, MakeTestingClusterSetting() is provided; the version 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. The version limits are initialized to the supplied range.

Note that the cluster version is not initialized (i.e. Version.Initialize() is not called).

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) 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 (
    Version19_1 VersionKey
    VersionStart19_2
    VersionQueryTxnTimestamp
    VersionStickyBit
    VersionParallelCommits
    VersionGenerationComparable
    VersionLearnerReplicas
    VersionTopLevelForeignKeys
    VersionAtomicChangeReplicasTrigger
    VersionAtomicChangeReplicas
    VersionTableDescModificationTimeFromMVCC
    VersionPartitionedBackup
    Version19_2
    VersionStart20_1
    VersionContainsEstimatesCounter
    VersionChangeReplicasDemotion
)

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