import "github.com/cockroachdb/cockroach/pkg/settings/cluster"
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.
// 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()`.
TelemetryOptOut is a place for controlling whether to opt out of telemetry or not.
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 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() ([]byte, []int)
func (cv ClusterVersion) IsActive(versionKey VersionKey) bool
IsActive returns true if the features of the supplied version are active at the running version.
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 (m *ClusterVersion) Marshal() (dAtA []byte, err error)
func (m *ClusterVersion) MarshalTo(dAtA []byte) (int, error)
func (*ClusterVersion) ProtoMessage()
func (m *ClusterVersion) Reset()
func (m *ClusterVersion) Size() (n int)
func (cv ClusterVersion) String() string
func (m *ClusterVersion) Unmarshal(dAtA []byte) error
func (m *ClusterVersion) XXX_DiscardUnknown()
func (dst *ClusterVersion) XXX_Merge(src proto.Message)
func (m *ClusterVersion) XXX_Size() int
func (m *ClusterVersion) XXX_Unmarshal(b []byte) error
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.
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).
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).
MakeTestingClusterSettings returns a Settings object that has had its version initialized to BinaryServerVersion.
MakeTestingClusterSettingsWithVersion returns a Settings object that has had its version initialized to the provided version configuration.
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.
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.
SetCPUProfiling is called from the pprofui to inform the system that a CPU profile is being recorded.
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 (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.