settings

package
v0.25.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 5, 2025 License: Apache-2.0 Imports: 24 Imported by: 0

Documentation

Overview

Package settings provides a central registry of runtime editable settings and accompanying helper functions for retrieving their current values.

Overview

Settings values are stored in the system.settings table. A rangefeed-driven worker updates the cached value when the table changes (see package 'settingswatcher').

To add a new setting, call one of the `Register` methods in `registry.go` and save the accessor created by the register function in the package where the setting is to be used. For example, to add an "enterprise" flag, adding into license_check.go: 

var enterpriseEnabled = settings.RegisterBoolSetting(
	settings.ApplicationLevel,
	"enterprise.enabled",
	"some doc for the setting",
	false,
)

Then use with `if enterpriseEnabled.Get(...) ...`

Setting names

Settings have both a "key" and a "name".

The key is what is used to persist the value and synchronize it across nodes. The key should remain immutable through the lifetime of the setting. This is the main argument passed through the Register() calls.

The name is what end-users see in docs and can use via the SQL statements SET/SHOW CLUSTER SETTING. It can change over time. It is also subject to a linter; for example boolean settings should have a name ending with '.enabled'.

When no name is specified, it defaults to the key. Another name can be specified using `WithName()`, for example: 

var mySetting = settings.RegisterBoolSetting(
	"mykey", ...,
	settings.WithName("descriptive.name.enabled"),
)

For convenience, users can also refer to a setting using its key in the SET/SHOW CLUSTER SETTING statements. Because of this, the keys and names are in the same namespace and cannot overlap.

Careful choice of default values, value propagation delay

Settings should always be defined with "safe" default values -- until a node receives values asynchronously, or even after that, if it cannot read them for some reason, it will use the default values, so define defaults that "fail safe".

In cases where the "safe" default doesn't actually match the desired default, like respecting an opt-*out* setting, we can default to `false` (opted out) and then use a migration to write an explicit `true`: in practice you'd still expect to read `true` unless a preference is expressed, but in the rare cases where you read a default, you don't risk ignoring an expressed opt-out.

Ideally, when passing configuration into some structure or subsystem, e.g. a rate limit into a client or something, passing a `*FooSetting` rather than a `Foo` and waiting to call `.Get()` until the value is actually used ensures observing the latest value.

Changing names of settings

Sometimes for UX or documentation purposes it is useful to rename a setting. However, to preserve backward-compatibility, its key cannot change.

There are two situations possible:

  • The setting currently has the same name as its key. To rename the setting, use the `WithName()` option.

  • The setting already has another name than its key. In this case, modify the name in the `WithName()` option and also add a `WithRetiredName()` option with the previous name. A SQL notice will redirect users to the new name.

Retiring settings

Settings may become irrelevant over time, especially when introduced to provide a workaround to a system limitation which is later corrected. There are two possible scenarios:

  • The setting may still be referred to from automation (e.g. external scripts). In this case, use the option `settings.Retired` at the registration point.

  • The setting will not ever be reused anywhere and can be deleted. When deleting a setting's registration from the codebase, add its name to the list of `retiredSettings` in settings/registry.go -- this ensures the name cannot be accidentally reused, and suppresses log spam about the existing value.

The list of deleted+retired settings can periodically (i.e. in major versions) be "flushed" by adding a migration that deletes all stored values for those keys at which point the key would be available for reuse in a later version. Is is only safe to run such a migration after the cluster upgrade process ensures no older nodes are still using the values for those old settings though, so such a migration needs to be version gated.

Index

Constants

View Source 
const ForSystemTenant = true

ForSystemTenant can be passed to Lookup for code that runs only on the system tenant.

View Source 
const ForVirtualCluster = false

ForVirtualCluster can be passed to Lookup for code that runs on virtual clusters.

View Source 
const MaxSettings = 1023

MaxSettings is the maximum number of settings that the system supports. Exported for tests.

View Source 
const VersionSettingValueType = "m"

VersionSettingValueType is the value type string (m originally for "migration") used in the system.settings table.

Variables

View Source 
var (
	ErrInvalidLengthEncoding        = fmt.Errorf("proto: negative length found during unmarshaling")
	ErrIntOverflowEncoding          = fmt.Errorf("proto: integer overflow")
	ErrUnexpectedEndOfGroupEncoding = fmt.Errorf("proto: unexpected end of group")
)
View Source 
var ReadableTypes = map[string]string{
	"s": "string",
	"i": "integer",
	"f": "float",
	"b": "boolean",
	"z": "byte size",
	"d": "duration",
	"e": "enumeration",

	"m": "version",
	"p": "protobuf",
}

ReadableTypes maps our short type identifiers to friendlier names.

View Source 
var TestOpaque interface{} = testOpaqueType{}

TestOpaque can be passed to Values.Init when we are testing the settings infrastructure.

Functions

func EncodeBool 

func EncodeBool(b bool) string

EncodeBool encodes a bool in the format of EncodedValue.Value.

func EncodeDuration 

func EncodeDuration(d time.Duration) string

EncodeDuration encodes a duration in the format of EncodedValue.Value.

func EncodeFloat 

func EncodeFloat(f float64) string

EncodeFloat encodes a float in the format of EncodedValue.Value.

func EncodeInt 

func EncodeInt(i int64) string

EncodeInt encodes an int in the format of EncodedValue.Value.

func EncodeProtobuf 

func EncodeProtobuf(p protoutil.Message) string

EncodeProtobuf encodes a protobuf in the format of EncodedValue.Value.

func IsIgnoringAllUpdates 

func IsIgnoringAllUpdates() bool

IsIgnoringAllUpdates returns true if Updaters returned by NewUpdater will discard all updates due to the COCKROACH_IGNORE_CLUSTER_SETTINGS var.

func LookupForDisplay 

func LookupForDisplay(
	name SettingName, forSystemTenant, canViewSensitive bool,
) (Setting, bool, NameStatus)

LookupForDisplay returns a Setting by key. Used when a setting is being retrieved for display in SHOW commands or crdb_internal tables.

For settings that are sensitive, the returned Setting hides the current value (see Setting.String) if canViewSensitive is false.

func LookupForLocalAccess 

func LookupForLocalAccess(
	name SettingName, forSystemTenant bool,
) (NonMaskedSetting, bool, NameStatus)

LookupForLocalAccess returns a NonMaskedSetting by name. Used when a setting is being retrieved for local processing within the cluster and not for reporting; sensitive values are accessible.

func NameToKey 

func NameToKey(name SettingName) (key InternalKey, found bool, nameStatus NameStatus)

NameToKey returns the key associated with a setting name.

func NumRegisteredSettings 

func NumRegisteredSettings() int

NumRegisteredSettings returns the number of registered settings.

func RedactedValue 

func RedactedValue(key InternalKey, values *Values, forSystemTenant bool) string

RedactedValue returns:

  • a string representation of the value, if the setting is reportable;
  • "<redacted>" if the setting is not reportable, sensitive, or a string;
  • "<unknown>" if there is no setting with this name.

func RegisterVersionSetting 

func RegisterVersionSetting(
	class Class, key InternalKey, desc string, setting *VersionSetting, opts ...SettingOption,
)

RegisterVersionSetting adds the provided version setting to the global registry.

func SettingPreviouslyHadApplicationClass 

func SettingPreviouslyHadApplicationClass(key InternalKey) bool

SettingPreviouslyHadApplicationClass returns true if the setting used to have the ApplicationLevel class.

func TestingIsReportable 

func TestingIsReportable(s Setting) bool

TestingIsReportable is used in testing for reportability.

func TestingIsSensitive 

func TestingIsSensitive(s Setting) bool

TestingIsSensitive is used in testing for sensitivity.

func TestingListPrevAppSettings 

func TestingListPrevAppSettings() map[InternalKey]struct{}

TestingListPrevAppSettings is exported for testing only.

func TestingSaveRegistry 

func TestingSaveRegistry() func()

TestingSaveRegistry can be used in tests to save/restore the current contents of the registry.

Types

type AnyEnumSetting 

type AnyEnumSetting interface {

	// ParseEnum parses a string that is either a string in enumValues or an
	// integer and returns the enum value as an int64 (and a boolean that
	// indicates if it was parseable).
	ParseEnum(raw string) (int64, bool)

	// GetAvailableValuesAsHint returns the possible enum settings as a string that
	// can be provided as an error hint to a user.
	GetAvailableValuesAsHint() string
	// contains filtered or unexported methods
}

AnyEnumSetting is an interface that is used when the specific enum type T is not known.

type BoolSetting 

type BoolSetting struct {
	// contains filtered or unexported fields
}

BoolSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bool" is updated.

func RegisterBoolSetting 

func RegisterBoolSetting(
	class Class, key InternalKey, desc string, defaultValue bool, opts ...SettingOption,
) *BoolSetting

RegisterBoolSetting defines a new setting with type bool.

func (BoolSetting) Class 

func (c BoolSetting) Class() Class

func (*BoolSetting) DecodeToString 

func (b *BoolSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*BoolSetting) DecodeValue 

func (b *BoolSetting) DecodeValue(encoded string) (bool, error)

DecodeValue decodes the value into a float.

func (*BoolSetting) Default 

func (b *BoolSetting) Default() bool

Default returns default value for setting.

func (*BoolSetting) DefaultString 

func (b *BoolSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (BoolSetting) Description 

func (c BoolSetting) Description() string

func (*BoolSetting) Encoded 

func (b *BoolSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*BoolSetting) EncodedDefault 

func (b *BoolSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*BoolSetting) ErrorHint 

func (c *BoolSetting) ErrorHint() (bool, string)

func (*BoolSetting) Get 

func (b *BoolSetting) Get(sv *Values) bool

Get retrieves the bool value in the setting.

func (BoolSetting) InternalKey 

func (c BoolSetting) InternalKey() InternalKey

func (*BoolSetting) IsUnsafe 

func (c *BoolSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (BoolSetting) Name 

func (c BoolSetting) Name() SettingName

func (*BoolSetting) Override 

func (b *BoolSetting) Override(ctx context.Context, sv *Values, v bool)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*BoolSetting) SetOnChange 

func (c *BoolSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*BoolSetting) String 

func (b *BoolSetting) String(sv *Values) string

func (*BoolSetting) Typ 

func (*BoolSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*BoolSetting) Validate 

func (b *BoolSetting) Validate(sv *Values, v bool) error

Validate that a value conforms with the validation function.

func (*BoolSetting) ValueOrigin 

func (c *BoolSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (BoolSetting) Visibility 

func (c BoolSetting) Visibility() Visibility

type ByteSizeSetting 

type ByteSizeSetting struct {
	IntSetting
}

ByteSizeSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "bytesize" is updated.

func RegisterByteSizeSetting 

func RegisterByteSizeSetting(
	class Class, key InternalKey, desc string, defaultValue int64, opts ...SettingOption,
) *ByteSizeSetting

RegisterByteSizeSetting defines a new setting with type bytesize and any supplied validation function(s). If no validation functions are given, then the non-negative int validation is performed.

func (ByteSizeSetting) Class 

func (c ByteSizeSetting) Class() Class

func (*ByteSizeSetting) DecodeToString 

func (b *ByteSizeSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*ByteSizeSetting) DefaultString 

func (b *ByteSizeSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (ByteSizeSetting) Description 

func (c ByteSizeSetting) Description() string

func (*ByteSizeSetting) ErrorHint 

func (c *ByteSizeSetting) ErrorHint() (bool, string)

func (ByteSizeSetting) InternalKey 

func (c ByteSizeSetting) InternalKey() InternalKey

func (*ByteSizeSetting) IsUnsafe 

func (c *ByteSizeSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (ByteSizeSetting) Name 

func (c ByteSizeSetting) Name() SettingName

func (*ByteSizeSetting) SetOnChange 

func (c *ByteSizeSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*ByteSizeSetting) String 

func (b *ByteSizeSetting) String(sv *Values) string

func (*ByteSizeSetting) Typ 

func (*ByteSizeSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*ByteSizeSetting) ValueOrigin 

func (c *ByteSizeSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (ByteSizeSetting) Visibility 

func (c ByteSizeSetting) Visibility() Visibility

type Class 

type Class int8

Class describes the scope of a setting under cluster virtualization.

Guidelines for choosing a class:

  • Make sure to read the descriptions below carefully to understand the differences in semantics.

  • Rules of thumb:

    1. if an end-user may benefit from modifying the setting through a SQL connection to a secondary tenant / virtual cluster, AND different virtual clusters should be able to use different values, the setting should have class ApplicationLevel.

    2. if a setting should only be controlled by SREs in a multi-tenant deployment or in an organization that wishes to shield DB operations from application development, OR the behavior of CockroachDB is not well-defined if multiple tenants (virtual clusters) use different values concurrently, the setting must *not* use class ApplicationLevel.

    3. if and only if a setting relevant to the KV/storage layer and whose value is shared across all virtual clusters is ever accessed by code in the application layer (SQL execution or HTTP handlers), use SystemVisible.

    4. in other cases, use SystemOnly. 

const (
	// SystemOnly settings are specific to the KV/storage layer and
	// cannot be accessed from application layer code (in particular not
	// from SQL layer nor HTTP handlers).
	//
	// As a rule of thumb, use this class if:
	//
	//   - the setting may be accessed from the shared KV/storage layer;
	//
	//   - AND, the setting should only be controllable by SREs (not
	//     end-users) in a multi-tenant environment, AND the behavior
	//     of CockroachDB is not well-defined if different virtual
	//     clusters were to use different values concurrently.
	//
	//     (If this part of the condition does not hold, consider
	//     ApplicationLevel instead.)
	//
	//   - AND, its value is never needed in the application layer (i.e.
	//     it is not read from SQL code, HTTP handlers or other code
	//     that would run in SQL pods in a multi-tenant environment).
	//
	//     (If this part of the condition does not hold, consider
	//     SystemVisible instead.)
	//
	//     Note: if a setting is only ever accessed in the SQL code
	//     after it has ascertained that it was running for the system
	//     interface; and we do not wish to display this setting in the
	//     list displayed by `SHOW ALL CLUSTER SETTINGS` in virtual
	//     clusters, the class SystemOnly is suitable. Hence the emphasis
	//     on "would run in SQL pods" above.
	SystemOnly Class = iota

	// SystemVisible settings are specific to the KV/storage layer and
	// are also visible to virtual clusters.
	//
	// As a rule of thumb, use this class if:
	//
	//   - the setting may be accessed from the shared KV/storage layer;
	//
	//   - AND the setting should only be controllable by operators of
	//     the storage cluster (e.g. SREs in the case of a multi-tenant
	//     environment) but having the storage cluster's value be
	//     observable by virtual clusters is desirable.
	//
	//     (If this part of the condition does not hold, consider
	//     ApplicationLevel instead.)
	//
	//   - AND, its value is sometimes needed in the application layer
	//     (i.e. it may be read from SQL code, HTTP handlers or other
	//     code that could run in SQL pods in a multi-tenant environment).
	//
	//     (If this part of the condition does not hold, consider
	//     SystemOnly instead.)
	//
	// One use cases is to enable optimizations in the KV client side of
	// virtual cluster RPCs. For example, if the storage layer uses a
	// setting to decide the size of a response, making the setting
	// visible enables the client in virtual cluster code to
	// pre-allocate response buffers to match the size they expect to
	// receive.
	//
	// Another use case is KV/storage feature flags, to enable a UX
	// improvement in virtual clusters by avoiding requesting
	// storage-level functionality when it is not enabled, such as
	// rangefeeds and provide a better error message.
	// (Without this extra logic, the error reported by KV/storage
	// might be hard to read by end-users.)
	//
	// As a reminder, the setting values observed by a virtual cluster,
	// both for its own application settings and those it observes for
	// system-visible settings, can be overridden using ALTER VIRTUAL
	// CLUSTER SET CLUSTER SETTING. This can be used during e.g.
	// troubleshooting, to allow changing the observed value for a
	// virtual cluster without a code change.
	//
	// A setting that is expected to be overridden in regular operation
	// to to control application-level behavior is still an application
	// setting, and should use the application class; system-visible is
	// for use by settings that control the storage layer but need to be
	// visible, rather than for settings that control the application
	// layer but are intended to be read-only. This latter case should
	// use ApplicationLayer, because it controls application behavior,
	// and then rely on an override to prevent modification from within
	// the virtual cluster.
	SystemVisible

	// ApplicationLevel settings are readable and can optionally be
	// modified by virtual clusters.
	//
	// As a rule of thumb, use this class if:
	//
	//   - the setting is never accessed by the shared KV/storage layer;
	//
	//   - AND, any of the following holds:
	//
	//     - end-users may benefit from modifying the setting
	//       through a SQL connection to a secondary tenant / virtual
	//       cluster.
	//
	//       (If this part of the condition does not hold, but the other
	//       part of the condition below does hold, consider still using
	//       ApplicationLevel and force an override using ALTER VIRTUAL
	//       CLUSTER SET CLUSTER SETTING. This makes the
	//       ApplicationLevel setting effectively read-only from the
	//       virtual cluster's perspective, because system overrides
	//       cannot be modified by the virtual cluster.)
	//
	//     - OR, different virtual clusters should be able to
	//       use different values for the setting.
	//
	//       (If this part of the condition does not hold, consider
	//       SystemOnly or SystemVisible instead.)
	//
	// Note that each SQL layer has its own copy of ApplicationLevel
	// settings; including the system tenant/interface. However, they
	// are neatly partitioned such that a given virtual cluster can
	// never observe the value set for another virtual cluster nor that
	// set for the system tenant/interface.
	//
	// As a reminder, the setting values observed by a virtual cluster,
	// both for its own application settings and those it observes for
	// system-visible settings, can be overridden using ALTER VIRTUAL
	// CLUSTER SET CLUSTER SETTING. This can be used during e.g.
	// troubleshooting, to allow changing the observed value for a
	// virtual cluster without a code change.
	ApplicationLevel
)

type ClusterVersionImpl 

type ClusterVersionImpl interface {
	fmt.Stringer

	// Encode encodes the ClusterVersion (using the protobuf encoding).
	Encode() []byte
}

ClusterVersionImpl is used to stub out the dependency on the ClusterVersion type (in pkg/clusterversion). The VersionSetting below is used to set ClusterVersion values, but we can't import the type directly due to the cyclical dependency structure.

type DurationSetting 

type DurationSetting struct {
	// contains filtered or unexported fields
}

DurationSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "duration" is updated.

func RegisterDurationSetting 

func RegisterDurationSetting(
	class Class, key InternalKey, desc string, defaultValue time.Duration, opts ...SettingOption,
) *DurationSetting

RegisterDurationSetting defines a new setting with type duration.

func (DurationSetting) Class 

func (c DurationSetting) Class() Class

func (*DurationSetting) DecodeToString 

func (d *DurationSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*DurationSetting) DecodeValue 

func (d *DurationSetting) DecodeValue(encoded string) (time.Duration, error)

DecodeValue decodes the value into a float.

func (*DurationSetting) Default 

func (d *DurationSetting) Default() time.Duration

Default returns default value for setting.

func (*DurationSetting) DefaultString 

func (d *DurationSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (DurationSetting) Description 

func (c DurationSetting) Description() string

func (*DurationSetting) Encoded 

func (d *DurationSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*DurationSetting) EncodedDefault 

func (d *DurationSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*DurationSetting) ErrorHint 

func (c *DurationSetting) ErrorHint() (bool, string)

func (*DurationSetting) Get 

func (d *DurationSetting) Get(sv *Values) time.Duration

Get retrieves the duration value in the setting.

func (DurationSetting) InternalKey 

func (c DurationSetting) InternalKey() InternalKey

func (*DurationSetting) IsUnsafe 

func (c *DurationSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (DurationSetting) Name 

func (c DurationSetting) Name() SettingName

func (*DurationSetting) Override 

func (d *DurationSetting) Override(ctx context.Context, sv *Values, v time.Duration)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*DurationSetting) SetOnChange 

func (c *DurationSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*DurationSetting) String 

func (d *DurationSetting) String(sv *Values) string

func (*DurationSetting) Typ 

func (*DurationSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*DurationSetting) Validate 

func (d *DurationSetting) Validate(v time.Duration) error

Validate that a value conforms with the validation function.

func (*DurationSetting) ValueOrigin 

func (c *DurationSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (DurationSetting) Visibility 

func (c DurationSetting) Visibility() Visibility

type DurationSettingWithExplicitUnit 

type DurationSettingWithExplicitUnit struct {
	DurationSetting
}

DurationSettingWithExplicitUnit is like DurationSetting except it requires an explicit unit when being set. (eg. 1s works, but 1 does not).

func RegisterDurationSettingWithExplicitUnit 

func RegisterDurationSettingWithExplicitUnit(
	class Class, key InternalKey, desc string, defaultValue time.Duration, opts ...SettingOption,
) *DurationSettingWithExplicitUnit

RegisterPublicDurationSettingWithExplicitUnit defines a new public setting with type duration which requires an explicit unit when being set.

func (DurationSettingWithExplicitUnit) Class 

func (c DurationSettingWithExplicitUnit) Class() Class

func (DurationSettingWithExplicitUnit) Description 

func (c DurationSettingWithExplicitUnit) Description() string

func (*DurationSettingWithExplicitUnit) ErrorHint 

func (d *DurationSettingWithExplicitUnit) ErrorHint() (bool, string)

ErrorHint returns a hint message to be displayed on error to the user.

func (DurationSettingWithExplicitUnit) InternalKey 

func (c DurationSettingWithExplicitUnit) InternalKey() InternalKey

func (*DurationSettingWithExplicitUnit) IsUnsafe 

func (c *DurationSettingWithExplicitUnit) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (DurationSettingWithExplicitUnit) Name 

func (c DurationSettingWithExplicitUnit) Name() SettingName

func (*DurationSettingWithExplicitUnit) SetOnChange 

func (c *DurationSettingWithExplicitUnit) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*DurationSettingWithExplicitUnit) ValueOrigin 

func (c *DurationSettingWithExplicitUnit) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (DurationSettingWithExplicitUnit) Visibility 

func (c DurationSettingWithExplicitUnit) Visibility() Visibility

type EncodedValue 

type EncodedValue struct {
	Value string `protobuf:"bytes,1,opt,name=value,proto3" json:"value,omitempty"`
	Type  string `protobuf:"bytes,2,opt,name=type,proto3" json:"type,omitempty"`
}

EncodedValue contains the value of a cluster setting serialized as an opaque string, along with a type identifier. Used when storing setting values on disk or passing them over the wire.

func (*EncodedValue) Descriptor 

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

func (*EncodedValue) Equal 

func (this *EncodedValue) Equal(that interface{}) bool

func (*EncodedValue) Marshal 

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

func (*EncodedValue) MarshalTo 

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

func (*EncodedValue) MarshalToSizedBuffer 

func (m *EncodedValue) MarshalToSizedBuffer(dAtA []byte) (int, error)

func (*EncodedValue) ProtoMessage 

func (*EncodedValue) ProtoMessage()

func (*EncodedValue) Reset 

func (m *EncodedValue) Reset()

func (EncodedValue) SafeFormat 

func (v EncodedValue) SafeFormat(s interfaces.SafePrinter, verb rune)

SafeFormat is part of redact.SafeFormatter.

func (*EncodedValue) Size 

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

func (EncodedValue) String 

func (v EncodedValue) String() string

String is part of fmt.Stringer.

func (*EncodedValue) Unmarshal 

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

func (*EncodedValue) XXX_DiscardUnknown 

func (m *EncodedValue) XXX_DiscardUnknown()

func (*EncodedValue) XXX_Marshal 

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

func (*EncodedValue) XXX_Merge 

func (m *EncodedValue) XXX_Merge(src proto.Message)

func (*EncodedValue) XXX_Size 

func (m *EncodedValue) XXX_Size() int

func (*EncodedValue) XXX_Unmarshal 

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

type EnumSetting 

type EnumSetting[T constraints.Integer] struct {
	// contains filtered or unexported fields
}

EnumSetting is a StringSetting that restricts the values to be one of the `enumValues`

func RegisterEnumSetting 

func RegisterEnumSetting[T constraints.Integer](
	class Class,
	key InternalKey,
	desc string,
	defaultValue string,
	enumValues map[T]string,
	opts ...SettingOption,
) *EnumSetting[T]

RegisterEnumSetting defines a new setting with type int.

func (EnumSetting) Class 

func (c EnumSetting) Class() Class

func (*EnumSetting[T]) DecodeToString 

func (e *EnumSetting[T]) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*EnumSetting[T]) DefaultString 

func (e *EnumSetting[T]) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (EnumSetting) Description 

func (c EnumSetting) Description() string

func (*EnumSetting[T]) Encoded 

func (e *EnumSetting[T]) Encoded(sv *Values) string

func (*EnumSetting[T]) EncodedDefault 

func (e *EnumSetting[T]) EncodedDefault() string

func (*EnumSetting) ErrorHint 

func (c *EnumSetting) ErrorHint() (bool, string)

func (*EnumSetting[T]) Get 

func (e *EnumSetting[T]) Get(sv *Values) T

Get retrieves the int value in the setting.

func (*EnumSetting[T]) GetAvailableValues 

func (e *EnumSetting[T]) GetAvailableValues() []string

GetAvailableValues returns the possible enum settings as a string slice.

func (*EnumSetting[T]) GetAvailableValuesAsHint 

func (e *EnumSetting[T]) GetAvailableValuesAsHint() string

GetAvailableValuesAsHint returns the possible enum settings as a string that can be provided as an error hint to a user.

func (EnumSetting) InternalKey 

func (c EnumSetting) InternalKey() InternalKey

func (*EnumSetting) IsUnsafe 

func (c *EnumSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (EnumSetting) Name 

func (c EnumSetting) Name() SettingName

func (*EnumSetting[T]) Override 

func (e *EnumSetting[T]) Override(ctx context.Context, sv *Values, v T)

Override changes the setting without validation and also overrides the default value.

func (*EnumSetting[T]) ParseEnum 

func (e *EnumSetting[T]) ParseEnum(raw string) (int64, bool)

ParseEnum parses a string that is either a string in enumValues or an integer and returns the enum value as an int64 (and a boolean that indicates if it was parseable).

func (*EnumSetting) SetOnChange 

func (c *EnumSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*EnumSetting[T]) String 

func (e *EnumSetting[T]) String(sv *Values) string

String returns the enum's string value.

func (*EnumSetting[T]) Typ 

func (e *EnumSetting[T]) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*EnumSetting) ValueOrigin 

func (c *EnumSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (EnumSetting) Visibility 

func (c EnumSetting) Visibility() Visibility

type FloatSetting 

type FloatSetting struct {
	// contains filtered or unexported fields
}

FloatSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "float" is updated.

func RegisterFloatSetting 

func RegisterFloatSetting(
	class Class, key InternalKey, desc string, defaultValue float64, opts ...SettingOption,
) *FloatSetting

RegisterFloatSetting defines a new setting with type float.

func (FloatSetting) Class 

func (c FloatSetting) Class() Class

func (*FloatSetting) DecodeToString 

func (f *FloatSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*FloatSetting) DecodeValue 

func (f *FloatSetting) DecodeValue(encoded string) (float64, error)

DecodeValue decodes the value into a float.

func (*FloatSetting) Default 

func (f *FloatSetting) Default() float64

Default returns default value for setting.

func (*FloatSetting) DefaultString 

func (f *FloatSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (FloatSetting) Description 

func (c FloatSetting) Description() string

func (*FloatSetting) Encoded 

func (f *FloatSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*FloatSetting) EncodedDefault 

func (f *FloatSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*FloatSetting) ErrorHint 

func (c *FloatSetting) ErrorHint() (bool, string)

func (*FloatSetting) Get 

func (f *FloatSetting) Get(sv *Values) float64

Get retrieves the float value in the setting.

func (FloatSetting) InternalKey 

func (c FloatSetting) InternalKey() InternalKey

func (*FloatSetting) IsUnsafe 

func (c *FloatSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (FloatSetting) Name 

func (c FloatSetting) Name() SettingName

func (*FloatSetting) Override 

func (f *FloatSetting) Override(ctx context.Context, sv *Values, v float64)

Override changes the setting panicking if validation fails and also overrides the default value.

For testing usage only.

func (*FloatSetting) SetOnChange 

func (c *FloatSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*FloatSetting) String 

func (f *FloatSetting) String(sv *Values) string

func (*FloatSetting) Typ 

func (*FloatSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*FloatSetting) Validate 

func (f *FloatSetting) Validate(v float64) error

Validate that a value conforms with the validation function.

func (*FloatSetting) ValueOrigin 

func (c *FloatSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (FloatSetting) Visibility 

func (c FloatSetting) Visibility() Visibility

type IntSetting 

type IntSetting struct {
	// contains filtered or unexported fields
}

IntSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "int" is updated.

func RegisterIntSetting 

func RegisterIntSetting(
	class Class, key InternalKey, desc string, defaultValue int64, opts ...SettingOption,
) *IntSetting

RegisterIntSetting defines a new setting with type int with a validation function.

func (IntSetting) Class 

func (c IntSetting) Class() Class

func (*IntSetting) DecodeNumericValue 

func (i *IntSetting) DecodeNumericValue(value string) (int64, error)

DecodeValue decodes the value into an integer.

func (*IntSetting) DecodeToString 

func (i *IntSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*IntSetting) Default 

func (i *IntSetting) Default() int64

Default returns default value for setting.

func (*IntSetting) DefaultString 

func (i *IntSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (IntSetting) Description 

func (c IntSetting) Description() string

func (*IntSetting) Encoded 

func (i *IntSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*IntSetting) EncodedDefault 

func (i *IntSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*IntSetting) ErrorHint 

func (c *IntSetting) ErrorHint() (bool, string)

func (*IntSetting) Get 

func (i *IntSetting) Get(sv *Values) int64

Get retrieves the int value in the setting.

func (IntSetting) InternalKey 

func (c IntSetting) InternalKey() InternalKey

func (*IntSetting) IsUnsafe 

func (c *IntSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (IntSetting) Name 

func (c IntSetting) Name() SettingName

func (*IntSetting) Override 

func (i *IntSetting) Override(ctx context.Context, sv *Values, v int64)

Override changes the setting without validation and also overrides the default value.

For testing usage only.

func (*IntSetting) SetOnChange 

func (c *IntSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*IntSetting) String 

func (i *IntSetting) String(sv *Values) string

func (*IntSetting) Typ 

func (*IntSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*IntSetting) Validate 

func (i *IntSetting) Validate(v int64) error

Validate that a value conforms with the validation function.

func (*IntSetting) ValueOrigin 

func (c *IntSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (IntSetting) Visibility 

func (c IntSetting) Visibility() Visibility

type InternalKey 

type InternalKey string

InternalKey is the internal (storage) key for a cluster setting. The internal key is suitable for use with: - direct accesses to system.settings. - rangefeed logic associated with system.settings. - (in unit tests only) interchangeably with the name for SET CLUSTER SETTING.

For user-visible displays, use the SettingName type instead.

func ConsoleKeys 

func ConsoleKeys() (res []InternalKey)

ConsoleKeys return an array with all cluster settings keys used by the UI Console. This list should only contain settings that have no sensitive information, because it will be returned on `settings` endpoint for users without VIEWCLUSTERSETTING or MODIFYCLUSTERSETTING permission, but that have VIEWACTIVITY or VIEWACTIVITYREDACTED permissions.

func Keys 

func Keys(forSystemTenant bool) (res []InternalKey)

Keys returns a sorted string array with all the known keys.

func SystemVisibleKeys 

func SystemVisibleKeys() []InternalKey

SystemVisibleKeys returns a array with all the known keys that have the class SystemVisible. It might not be sorted. The caller must refrain from modifying the return value.

func (InternalKey) SafeValue 

func (InternalKey) SafeValue()

SafeValue implements the redact.SafeValue interface.

type MaskedSetting 

type MaskedSetting struct {
	// contains filtered or unexported fields
}

MaskedSetting is a wrapper for non-reportable settings that were retrieved for reporting (see SetReportable and LookupForReportingByKey).

func (*MaskedSetting) Class 

func (s *MaskedSetting) Class() Class

Class returns the class for the underlying setting.

func (*MaskedSetting) DefaultString 

func (s *MaskedSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (*MaskedSetting) Description 

func (s *MaskedSetting) Description() string

Description returns the description string for the underlying setting.

func (*MaskedSetting) InternalKey 

func (s *MaskedSetting) InternalKey() InternalKey

InternalKey returns the key string for the underlying setting.

func (*MaskedSetting) IsUnsafe 

func (s *MaskedSetting) IsUnsafe() bool

IsUnsafe returns whether the underlying setting is unsafe.

func (*MaskedSetting) Name 

func (s *MaskedSetting) Name() SettingName

Name returns the name string for the underlying setting.

func (*MaskedSetting) String 

func (s *MaskedSetting) String(sv *Values) string

String hides the underlying value.

func (*MaskedSetting) Typ 

func (s *MaskedSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*MaskedSetting) ValueOrigin 

func (s *MaskedSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (*MaskedSetting) Visibility 

func (s *MaskedSetting) Visibility() Visibility

Visibility returns the visibility setting for the underlying setting.

type NameStatus 

type NameStatus bool

NameStatus indicates the status of a setting name. 

const (
	// NameActive indicates that the name is currently in use.
	NameActive NameStatus = true
	// NameRetired indicates that the name is no longer in use.
	NameRetired NameStatus = false
)

type NonMaskedSetting 

type NonMaskedSetting interface {
	Setting

	// Encoded returns the encoded representation of the current value of the
	// setting.
	Encoded(sv *Values) string

	// EncodedDefault returns the encoded representation of the default value of
	// the setting.
	EncodedDefault() string

	// DecodeToString returns the string representation of the provided
	// encoded value.
	// This is analogous to loading the setting from storage and
	// then calling String() on it, however the setting is not modified.
	// The string representation of the default value can be obtained
	// by calling EncodedDefault() and then DecodeToString().
	DecodeToString(encoded string) (repr string, err error)

	// SetOnChange installs a callback to be called when a setting's value
	// changes. `fn` should avoid doing long-running or blocking work as it is
	// called on the goroutine which handles all settings updates.
	SetOnChange(sv *Values, fn func(ctx context.Context))

	// ErrorHint returns a hint message to be displayed to the user when there's
	// an error.
	ErrorHint() (bool, string)
}

NonMaskedSetting is the exported interface of non-masked settings. A non-masked setting provides access to the current value (even if the setting is not reportable).

A non-masked setting must not be used in the context of reporting values (see LookupForReportingByKey).

func LookupForLocalAccessByKey 

func LookupForLocalAccessByKey(key InternalKey, forSystemTenant bool) (NonMaskedSetting, bool)

LookupForLocalAccessByKey returns a NonMaskedSetting by key. Used when a setting is being retrieved for local processing within the cluster and not for reporting; sensitive values are accessible.

type NoopUpdater 

type NoopUpdater struct{}

A NoopUpdater ignores all updates.

func (NoopUpdater) ResetRemaining 

func (u NoopUpdater) ResetRemaining(context.Context)

ResetRemaining implements Updater. It is a no-op.

func (NoopUpdater) Set 

func (u NoopUpdater) Set(ctx context.Context, key InternalKey, value EncodedValue) error

Set implements Updater. It is a no-op.

func (NoopUpdater) SetFromStorage 

func (u NoopUpdater) SetFromStorage(
	ctx context.Context, key InternalKey, value EncodedValue, origin ValueOrigin,
) error

SetFromStorage implements Updater. It is a no-op.

func (NoopUpdater) SetToDefault 

func (u NoopUpdater) SetToDefault(ctx context.Context, key InternalKey) error

SetToDefault implements Updater. It is a no-op.

type ProtobufSetting 

type ProtobufSetting struct {
	// contains filtered or unexported fields
}

ProtobufSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "protobuf" is updated. The proto message is held in memory, the byte representation stored in system.settings, and JSON presentation used when accepting input and rendering (just through SHOW CLUSTER SETTING <setting-name>, the raw form is visible when looking directly at system.settings).

func RegisterProtobufSetting 

func RegisterProtobufSetting(
	class Class, key InternalKey, desc string, defaultValue protoutil.Message, opts ...SettingOption,
) *ProtobufSetting

RegisterProtobufSetting defines a new setting with type protobuf.

func (ProtobufSetting) Class 

func (c ProtobufSetting) Class() Class

func (*ProtobufSetting) DecodeToString 

func (s *ProtobufSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*ProtobufSetting) DecodeValue 

func (s *ProtobufSetting) DecodeValue(encoded string) (protoutil.Message, error)

DecodeValue decodes the value into a protobuf.

func (*ProtobufSetting) Default 

func (s *ProtobufSetting) Default() protoutil.Message

Default returns default value for setting.

func (*ProtobufSetting) DefaultString 

func (s *ProtobufSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (ProtobufSetting) Description 

func (c ProtobufSetting) Description() string

func (*ProtobufSetting) Encoded 

func (s *ProtobufSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*ProtobufSetting) EncodedDefault 

func (s *ProtobufSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*ProtobufSetting) ErrorHint 

func (c *ProtobufSetting) ErrorHint() (bool, string)

func (*ProtobufSetting) Get 

func (s *ProtobufSetting) Get(sv *Values) protoutil.Message

Get retrieves the protobuf value in the setting.

func (ProtobufSetting) InternalKey 

func (c ProtobufSetting) InternalKey() InternalKey

func (*ProtobufSetting) IsUnsafe 

func (c *ProtobufSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (*ProtobufSetting) MarshalToJSON 

func (s *ProtobufSetting) MarshalToJSON(p protoutil.Message) (string, error)

MarshalToJSON returns a JSON representation of the protobuf.

func (ProtobufSetting) Name 

func (c ProtobufSetting) Name() SettingName

func (*ProtobufSetting) Override 

func (s *ProtobufSetting) Override(ctx context.Context, sv *Values, p protoutil.Message)

Override sets the setting to the given value, assuming it passes validation.

func (*ProtobufSetting) SetOnChange 

func (c *ProtobufSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*ProtobufSetting) String 

func (s *ProtobufSetting) String(sv *Values) string

String returns the string representation of the setting's current value.

func (*ProtobufSetting) Typ 

func (*ProtobufSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*ProtobufSetting) UnmarshalFromJSON 

func (s *ProtobufSetting) UnmarshalFromJSON(jsonEncoded string) (protoutil.Message, error)

UnmarshalFromJSON unmarshals a protobuf from a json representation.

func (*ProtobufSetting) Validate 

func (s *ProtobufSetting) Validate(sv *Values, p protoutil.Message) error

Validate that a value conforms with the validation function.

func (*ProtobufSetting) ValueOrigin 

func (c *ProtobufSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (ProtobufSetting) Visibility 

func (c ProtobufSetting) Visibility() Visibility

type Setting 

type Setting interface {
	// Class returns the scope of the setting in multi-tenant scenarios.
	Class() Class

	// InternalKey returns the internal key used to store the setting.
	// To display the name of the setting (eg. in errors etc) or the
	// SET/SHOW CLUSTER SETTING statements, use the Name() method instead.
	//
	// The internal key is suitable for use with:
	// - direct accesses to system.settings.
	// - rangefeed logic associated with system.settings.
	// - (in unit tests only) interchangeably with the name for SET CLUSTER SETTING.
	InternalKey() InternalKey

	// Name is the user-visible (display) name of the setting.
	// The name is suitable for:
	// - SHOW/SET CLUSTER SETTING.
	// - inclusion in error messages.
	Name() SettingName

	// Typ returns the short (1 char) string denoting the type of setting.
	Typ() string

	// String returns the string representation of the setting's current value.
	// It's used when materializing results for `SHOW CLUSTER SETTINGS` or `SHOW
	// CLUSTER SETTING <setting-name>`.
	//
	// If this object implements a non-reportable setting that was retrieved for
	// reporting (see LookupForReportingByKey), String hides the actual value.
	String(sv *Values) string

	// DefaultString returns the default value for the setting as a string. This
	// is the same as calling String on the setting when it was never set.
	DefaultString() string

	// Description contains a helpful text explaining what the specific cluster
	// setting is for.
	Description() string

	// Visibility returns whether the setting is made publicly visible. Reserved
	// settings are still accessible to users, but they don't get listed out when
	// retrieving all settings.
	Visibility() Visibility

	// IsUnsafe returns whether the setting is unsafe, and thus requires
	// a special interlock to set.
	IsUnsafe() bool

	// ValueOrigin returns the origin of the current value.
	ValueOrigin(ctx context.Context, sv *Values) ValueOrigin
}

Setting is the interface exposing the metadata for a cluster setting.

The values for the settings are stored separately in Values. This allows having a global (singleton) settings registry while allowing potentially multiple "instances" (values) for each setting (e.g. for multiple test servers in the same process).

func LookupForDisplayByKey 

func LookupForDisplayByKey(
	key InternalKey, forSystemTenant, canViewSensitive bool,
) (Setting, bool)

LookupForDisplayByKey returns a Setting by key. Used when a setting is being retrieved for display in SHOW commands or crdb_internal tables.

For settings that are sensitive, the returned Setting hides the current value (see Setting.String) if canViewSensitive is false.

func LookupForReportingByKey 

func LookupForReportingByKey(key InternalKey, forSystemTenant bool) (Setting, bool)

LookupForReportingByKey returns a Setting by key. Used when a setting is being retrieved for reporting.

For settings that are non-reportable, the returned Setting hides the current value (see Setting.String).

type SettingName 

type SettingName string

SettingName represents the user-visible name of a cluster setting. The name is suitable for: - SHOW/SET CLUSTER SETTING. - inclusion in error messages.

For internal storage, use the InternalKey type instead.

func (SettingName) SafeValue 

func (SettingName) SafeValue()

SafeValue implements the redact.SafeValue interface.

type SettingOption 

type SettingOption struct {
	// contains filtered or unexported fields
}

SettingOption is the type of an option that can be passed to Register. 

var Fraction SettingOption = FloatInRange(0, 1)

Fraction requires the setting to be in the interval [0, 1]. It can be passed to RegisterFloatSetting. 

var FractionUpperExclusive SettingOption = FloatInRangeUpperExclusive(0, 1)

FractionUpperExclusive requires the setting to be in the interval [0, 1). It can be passed to RegisterFloatSetting. 

var NonNegativeDuration SettingOption = WithValidateDuration(nonNegativeDurationInternal)

NonNegativeDuration checks that the duration is greater or equal to zero. It can be passed to RegisterDurationSetting. 

var NonNegativeFloat SettingOption = FloatWithMinimum(0)

NonNegativeFloat checks the value is greater or equal to zero. It can be passed to RegisterFloatSetting. 

var NonNegativeInt SettingOption = WithValidateInt(nonNegativeIntInternal)

NonNegativeInt checks the value is zero or positive. It can be passed to RegisterIntSetting. 

var NonZeroFloat SettingOption = WithValidateFloat(func(v float64) error {
	if v == 0 {
		return errors.New("cannot set to zero value")
	}
	return nil
})

NonZeroFloat checks that the value is non-zero. It can be passed to RegisterFloatSetting. 

var PositiveDuration SettingOption = WithValidateDuration(func(v time.Duration) error {
	if v <= 0 {
		return errors.Errorf("cannot be set to a non-positive duration: %s", v)
	}
	return nil
})

PositiveDuration checks that the value is strictly positive. It can be passed to RegisterDurationSetting. 

var PositiveFloat SettingOption = WithValidateFloat(func(v float64) error {
	if v <= 0 {
		return errors.Errorf("cannot set to a non-positive value: %f", v)
	}
	return nil
})

PositiveFloat checks that the value is strictly greater than zero. It can be passed to RegisterFloatSetting. 

var PositiveInt SettingOption = WithValidateInt(func(v int64) error {
	if v <= 0 {
		return errors.Errorf("cannot be set to a non-positive value: %d", v)
	}
	return nil
})

PositiveInt can be passed to RegisterIntSetting. 

var Retired SettingOption = SettingOption{
	// contains filtered or unexported fields
}

Retired marks the setting as obsolete. It also hides it from the output of SHOW CLUSTER SETTINGS. Note: in many case the setting definition can be removed outright, and its name added to the retiredSettings map (in settings/registry.go). The Retired option exists for cases where there is a need to maintain compatibility with automation. 

var Sensitive SettingOption = SettingOption{
	// contains filtered or unexported fields
}

Sensitive marks the setting as sensitive, which means that it will always be redacted in any output. It also makes the setting non-reportable. It can only be used for string settings. 

var WithPublic SettingOption = WithVisibility(Public)

WithPublic sets public visibility. 

var WithUnsafe SettingOption = SettingOption{
	// contains filtered or unexported fields
}

WithUnsafe indicates that the setting is unsafe. Unsafe settings need an interlock to be updated. They also cannot be public.

func ByteSizeWithMinimum 

func ByteSizeWithMinimum(minVal int64) SettingOption

ByteSizeWithMinimum can be passed to RegisterByteSizeSetting.

func DurationInRange 

func DurationInRange(minVal, maxVal time.Duration) SettingOption

DurationInRange returns a validation option that checks the value is within the given bounds (inclusive).

func DurationWithMinimum 

func DurationWithMinimum(minValue time.Duration) SettingOption

DurationWithMinimum returns a validation option that checks the duration is greater or equal to the given minimum. It can be passed to RegisterDurationSetting.

func DurationWithMinimumOrZeroDisable 

func DurationWithMinimumOrZeroDisable(minValue time.Duration) SettingOption

DurationWithMinimumOrZeroDisable returns a validation option that checks the value is at least the given minimum, or zero to disable. It can be passed to RegisterDurationSetting.

func FloatInRange 

func FloatInRange(minVal, maxVal float64) SettingOption

FloatInRange returns a validation option that checks the value is within the given bounds (inclusive).

func FloatInRangeUpperExclusive 

func FloatInRangeUpperExclusive(minVal, maxVal float64) SettingOption

FloatInRangeUpperExclusive returns a validation option that checks the value is within the given bounds (inclusive lower, exclusive upper).

func FloatWithMinimum 

func FloatWithMinimum(minVal float64) SettingOption

FloatWithMinimum returns a validation option that checks that the value is at least the given minimum. It can be passed to RegisterFloatSetting.

func FloatWithMinimumOrZeroDisable 

func FloatWithMinimumOrZeroDisable(minVal float64) SettingOption

FloatWithMinimumOrZeroDisable returns a validation option that verifies the value is at least the given minimum, or zero to disable. It can be passed to RegisterFloatSetting.

func IntInRange 

func IntInRange(minVal, maxVal int64) SettingOption

IntInRange returns a validation option that checks the value is within the given bounds (inclusive). It can be passed to RegisterIntSetting.

func IntInRangeOrZeroDisable 

func IntInRangeOrZeroDisable(minVal, maxVal int64) SettingOption

IntInRangeOrZeroDisable returns a validation option that checks the value is within the given bounds (inclusive) or is zero (disabled). It can be passed to RegisterIntSetting.

func IntWithMinimum 

func IntWithMinimum(minVal int64) SettingOption

IntWithMinimum returns a validation option that checks that the value is greater or equal to the given minimum. It can be passed to RegisterIntSetting.

func NonNegativeDurationWithMaximum 

func NonNegativeDurationWithMaximum(maxValue time.Duration) SettingOption

NonNegativeDurationWithMaximum returns a validation option that checks the duration is in the range [0, maxValue]. It can be passed to RegisterDurationSetting.

func NonNegativeFloatWithMaximum 

func NonNegativeFloatWithMaximum(maxValue float64) SettingOption

NonNegativeFloatWithMaximum returns a validation option that checks that the value is in the range [0, maxValue]. It can be passed to RegisterFloatSetting.

func NonNegativeIntWithMaximum 

func NonNegativeIntWithMaximum(maxValue int64) SettingOption

NonNegativeIntWithMaximum returns a validation option that checks that the value is in the range [0, maxValue]. It can be passed to RegisterIntSetting.

func WithName 

func WithName(name SettingName) SettingOption

WithName configures the user-visible name of the setting.

func WithReportable 

func WithReportable(reportable bool) SettingOption

WithReportable indicates whether a setting's value can show up in SHOW ALL CLUSTER SETTINGS and telemetry reports.

func WithRetiredName 

func WithRetiredName(name SettingName) SettingOption

WithRetiredName configures a previous user-visible name of the setting, when that name was different from the key and is not in use any more.

func WithValidateBool 

func WithValidateBool(fn func(*Values, bool) error) SettingOption

WithValidateBool adds a validation function for a boolean setting.

func WithValidateDuration 

func WithValidateDuration(fn func(time.Duration) error) SettingOption

WithValidateDuration adds a validation function for a duration setting.

func WithValidateFloat 

func WithValidateFloat(fn func(float64) error) SettingOption

WithValidateFloat adds a validation function for a float64 setting.

func WithValidateInt 

func WithValidateInt(fn func(int64) error) SettingOption

WithValidateInt adds a validation function for an int64 setting.

func WithValidateProto 

func WithValidateProto(fn func(*Values, protoutil.Message) error) SettingOption

WithValidateProto adds a validation function for a proto setting.

func WithValidateString 

func WithValidateString(fn func(*Values, string) error) SettingOption

WithValidateString adds a validation function for a string setting.

func WithVisibility 

func WithVisibility(v Visibility) SettingOption

WithVisibility customizes the visibility of a setting.

type StringSetting 

type StringSetting struct {
	// contains filtered or unexported fields
}

StringSetting is the interface of a setting variable that will be updated automatically when the corresponding cluster-wide setting of type "string" is updated.

func RegisterStringSetting 

func RegisterStringSetting(
	class Class, key InternalKey, desc string, defaultValue string, opts ...SettingOption,
) *StringSetting

RegisterStringSetting defines a new setting with type string.

func (StringSetting) Class 

func (c StringSetting) Class() Class

func (*StringSetting) DecodeToString 

func (s *StringSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*StringSetting) Default 

func (s *StringSetting) Default() string

Default returns default value for setting.

func (*StringSetting) DefaultString 

func (s *StringSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (StringSetting) Description 

func (c StringSetting) Description() string

func (*StringSetting) Encoded 

func (s *StringSetting) Encoded(sv *Values) string

Encoded returns the encoded value of the current value of the setting.

func (*StringSetting) EncodedDefault 

func (s *StringSetting) EncodedDefault() string

EncodedDefault returns the encoded value of the default value of the setting.

func (*StringSetting) ErrorHint 

func (c *StringSetting) ErrorHint() (bool, string)

func (*StringSetting) Get 

func (s *StringSetting) Get(sv *Values) string

Get retrieves the string value in the setting.

func (StringSetting) InternalKey 

func (c StringSetting) InternalKey() InternalKey

func (*StringSetting) IsUnsafe 

func (c *StringSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (StringSetting) Name 

func (c StringSetting) Name() SettingName

func (*StringSetting) Override 

func (s *StringSetting) Override(ctx context.Context, sv *Values, v string)

Override sets the setting to the given value, assuming it passes validation.

func (*StringSetting) SetOnChange 

func (c *StringSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*StringSetting) String 

func (s *StringSetting) String(sv *Values) string

func (*StringSetting) Typ 

func (*StringSetting) Typ() string

Typ returns the short (1 char) string denoting the type of setting.

func (*StringSetting) Validate 

func (s *StringSetting) Validate(sv *Values, v string) error

Validate that a value conforms with the validation function.

func (*StringSetting) ValueOrigin 

func (c *StringSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (StringSetting) Visibility 

func (c StringSetting) Visibility() Visibility

type Updater 

type Updater interface {
	// Set is used by tests to configure overrides in a generic fashion.
	Set(ctx context.Context, key InternalKey, value EncodedValue) error
	// SetToDefault resets the setting to its default value.
	SetToDefault(ctx context.Context, key InternalKey) error

	// ResetRemaining loads the values from build-time defaults for all
	// settings that were not updated by Set() and SetFromStorage().
	ResetRemaining(ctx context.Context)

	// SetFromStorage is called by the settings watcher to update the
	// settings from either the rangefeed over system.settings, or
	// overrides coming in over the network from the system tenant.
	SetFromStorage(ctx context.Context, key InternalKey, value EncodedValue, origin ValueOrigin) error
}

Updater is a helper for updating the in-memory settings.

RefreshSettings passes the serialized representations of all individual settings -- e.g. the rows read from the system.settings table. We update the wrapped atomic settings values as we go and note which settings were updated, then set the rest to default in ResetRemaining().

func NewUpdater 

func NewUpdater(sv *Values) Updater

NewUpdater makes an Updater.

type ValueOrigin 

type ValueOrigin uint32

ValueOrigin indicates the origin of the current value of a setting, e.g. if it is coming from the in-code default or an explicit override. 

const (
	// OriginDefault indicates the value in use is the default value.
	OriginDefault ValueOrigin = iota
	// OriginExplicitlySet indicates the value is has been set explicitly.
	OriginExplicitlySet
	// OriginExternallySet indicates the value has been set externally, such as
	// via a host-cluster override for this or all tenant(s).
	OriginExternallySet
	// OriginOverride indicates the value has been set via a test override.
	OriginOverride
)

func (ValueOrigin) SafeValue 

func (ValueOrigin) SafeValue()

SafeValue implements the redact.SafeValue interface.

func (ValueOrigin) String 

func (v ValueOrigin) String() string

type Values 

type Values struct {
	// contains filtered or unexported fields
}

Values is a container that stores values for all registered settings. Each setting is assigned a unique slot (up to MaxSettings). Note that slot indices are 1-based (this is to trigger panics if an uninitialized slot index is used).

func (*Values) Init 

func (sv *Values) Init(ctx context.Context, opaque interface{})

Init must be called before using a Values instance; it initializes all variables to their defaults.

The opaque argument can be retrieved later via Opaque().

func (*Values) Opaque 

func (sv *Values) Opaque() interface{}

Opaque returns the argument passed to Init.

func (*Values) SpecializeForSystemInterface 

func (sv *Values) SpecializeForSystemInterface()

SpecializeForSystemInterface marks the values container as pertaining to the system interface.

func (*Values) SpecializeForVirtualCluster 

func (sv *Values) SpecializeForVirtualCluster()

SpecializeForVirtualCluster marks this container as pertaining to a virtual cluster, after which use of SystemOnly values is disallowed.

func (*Values) SpecializedToVirtualCluster 

func (sv *Values) SpecializedToVirtualCluster() bool

SpecializedToVirtualCluster returns true if this container is for a virtual cluster (i.e. SpecializeToVirtualCluster() was called).

func (*Values) TestingCopyForServer 

func (sv *Values) TestingCopyForServer(input *Values, newOpaque interface{})

TestingCopyForServer makes a copy of the input Values in the target Values for use when initializing a server in a test cluster. This is meant to propagate initial values and overrides.

func (*Values) TestingCopyForVirtualCluster 

func (sv *Values) TestingCopyForVirtualCluster(input *Values)

TestingCopyForVirtualCluster makes a copy of the input Values in the target Values for use when initializing a server for a virtual cluster in tests. This is meant to propagate overrides to ApplicationLevel settings.

type VersionSetting 

type VersionSetting struct {
	// contains filtered or unexported fields
}

VersionSetting is the setting type that allows users to control the cluster version. It starts off at an initial version and takes into account the current version to validate proposed updates. This is (necessarily) tightly coupled with the setting implementation in pkg/clusterversion, and it's done through the VersionSettingImpl interface. We rely on the implementation to decode to and from raw bytes, and to perform the validation itself. The VersionSetting itself is then just the tiny shim that lets us hook into the rest of the settings machinery (by interfacing with Values, to load and store cluster versions).

TODO(irfansharif): If the cluster version is no longer backed by gossip, maybe we should stop pretending it's a regular gossip-backed cluster setting. We could introduce new syntax here to motivate this shift.

func MakeVersionSetting 

func MakeVersionSetting(impl VersionSettingImpl) VersionSetting

MakeVersionSetting instantiates a version setting instance. See VersionSetting for additional commentary.

func (VersionSetting) Class 

func (c VersionSetting) Class() Class

func (*VersionSetting) DecodeToString 

func (v *VersionSetting) DecodeToString(encoded string) (string, error)

DecodeToString decodes and renders an encoded value.

func (*VersionSetting) DefaultString 

func (v *VersionSetting) DefaultString() string

DefaultString returns the default value for the setting as a string.

func (VersionSetting) Description 

func (c VersionSetting) Description() string

func (*VersionSetting) Encoded 

func (v *VersionSetting) Encoded(sv *Values) string

Encoded is part of the NonMaskedSetting interface.

func (*VersionSetting) EncodedDefault 

func (v *VersionSetting) EncodedDefault() string

EncodedDefault is part of the NonMaskedSetting interface.

func (*VersionSetting) ErrorHint 

func (c *VersionSetting) ErrorHint() (bool, string)

func (*VersionSetting) GetInternal 

func (v *VersionSetting) GetInternal(sv *Values) ClusterVersionImpl

GetInternal returns the setting's current value.

func (VersionSetting) InternalKey 

func (c VersionSetting) InternalKey() InternalKey

func (*VersionSetting) IsUnsafe 

func (c *VersionSetting) IsUnsafe() bool

IsUnsafe indicates whether the setting is unsafe.

func (VersionSetting) Name 

func (c VersionSetting) Name() SettingName

func (*VersionSetting) SetInternal 

func (v *VersionSetting) SetInternal(ctx context.Context, sv *Values, newVal ClusterVersionImpl)

SetInternal updates the setting's value in the provided Values container.

func (*VersionSetting) SetOnChange 

func (c *VersionSetting) SetOnChange(sv *Values, fn func(ctx context.Context))

SetOnChange installs a callback to be called when a setting's value changes. `fn` should avoid doing long-running or blocking work as it is called on the goroutine which handles all settings updates.

func (*VersionSetting) SettingsListDefault 

func (v *VersionSetting) SettingsListDefault() string

SettingsListDefault returns the value that should be presented by `./cockroach gen settings-list`.

func (*VersionSetting) String 

func (v *VersionSetting) String(sv *Values) string

String is part of the Setting interface.

func (*VersionSetting) Typ 

func (*VersionSetting) Typ() string

Typ is part of the Setting interface.

func (*VersionSetting) Validate 

func (v *VersionSetting) Validate(ctx context.Context, sv *Values, oldV, newV []byte) error

Validate checks whether an version update is permitted. It takes in the old and the proposed new value (both in encoded form). This is called by SET CLUSTER SETTING.

func (*VersionSetting) ValueOrigin 

func (c *VersionSetting) ValueOrigin(ctx context.Context, sv *Values) ValueOrigin

ValueOrigin returns the origin of the current value of the setting.

func (VersionSetting) Visibility 

func (c VersionSetting) Visibility() Visibility

type VersionSettingImpl 

type VersionSettingImpl interface {
	// Decode takes in an encoded cluster version and returns it as the native
	// type (the clusterVersion proto). Except it does it through the
	// ClusterVersionImpl to avoid circular dependencies.
	Decode(val []byte) (ClusterVersionImpl, error)

	// Validate checks whether an version update is permitted. It takes in the
	// old and the proposed new value (both in encoded form). This is called by
	// SET CLUSTER SETTING.
	ValidateVersionUpgrade(ctx context.Context, sv *Values, oldV, newV []byte) error

	// ValidateBinaryVersions is a subset of Validate. It only checks that the
	// current binary supports the proposed version. This is called when the
	// version is being communicated to us by a different node (currently
	// through gossip).
	//
	// TODO(irfansharif): Update this comment when we stop relying on gossip to
	// propagate version bumps.
	ValidateBinaryVersions(ctx context.Context, sv *Values, newV []byte) error

	// SettingsListDefault returns the value that should be presented by
	// `./cockroach gen settings-list`
	SettingsListDefault() string
}

VersionSettingImpl is the interface bridging pkg/settings and pkg/clusterversion. See VersionSetting for additional commentary.

type Visibility 

type Visibility int8

Visibility describes how a user should feel confident that they can customize the setting.

See the constant definitions below for details. 

const (
	// Reserved - which is the default - indicates that a setting is
	// not documented and the CockroachDB team has not developed
	// internal experience about the impact of customizing it to other
	// values.
	// In short: "Use at your own risk."
	Reserved Visibility = iota
	// Public indicates that a setting is documented, the range of
	// possible values yields predictable results, and the CockroachDB
	// team is there to assist if issues occur as a result of the
	// customization.
	// In short: "Go ahead but be careful."
	Public
)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.