config

Documentation

Overview

Package config is the knob catalogue for vec (spec 22). It holds the single table of every configuration parameter: name, mutability tier, value kind, default, allowed range, and the documentation cross-reference. The vec package reads this table to validate PRAGMA and Option values, resolve effective settings, and render the configuration view. The package has no dependency on the engine, so the table can be tested on its own.

Index

• func ParseSize(raw string) (int64, error)
• type Kind
  • func (k Kind) String() string
• type Knob
  • func All() []Knob
  • func Lookup(name string) (*Knob, bool)
  • func WithPrefix(prefix string) []Knob
  • func (k *Knob) Canonicalize(raw string) (string, error)
  • func (k *Knob) IsEnum(v string) (string, bool)
• type Tier
  • func (t Tier) String() string
• type ValueError
  • func (e *ValueError) Error() string

Functions

func ParseSize

func ParseSize(raw string) (int64, error)

ParseSize exposes the size parser so the vec package can read byte-suffixed values from env variables and DSN query strings the same way PRAGMA does.

Types

type Kind

type Kind int

Kind is the value type of a knob, which decides how a raw string is parsed and range-checked.

const (
	// KindInt is a signed integer knob.
	KindInt Kind = iota
	// KindFloat is a floating-point knob.
	KindFloat
	// KindBool is an on/off knob.
	KindBool
	// KindEnum is one of a fixed set of string tokens.
	KindEnum
	// KindString is a free-form string (paths, addresses, URIs).
	KindString
	// KindFloatList is a bracketed list of floats, for fusion weights.
	KindFloatList
)

func (Kind) String

func (k Kind) String() string

String renders the kind for the configuration view.

type Knob

type Knob struct {
	// Name is the canonical knob name, as written in PRAGMA and config keys.
	Name string
	// Aliases are short forms that resolve to this knob (ef_search -> hnsw_ef_search).
	Aliases []string
	// Category groups the knob in the configuration view ("hnsw", "durability").
	Category string
	// Tier is the mutability tier.
	Tier Tier
	// Kind is the value type.
	Kind Kind
	// Default is the canonical string form of the compiled-in default.
	Default string
	// Computed is set when the default is derived from the environment at runtime
	// (adaptive cache, GOMAXPROCS, sqrt(N)); Default then holds a descriptive word.
	Computed bool
	// Enum lists the allowed tokens for a KindEnum knob, in canonical case.
	Enum []string
	// Min and Max bound a numeric knob when HasMin or HasMax is set.
	Min, Max       float64
	HasMin, HasMax bool
	// PowerOfTwo requires an integer knob to be a power of two (page_size).
	PowerOfTwo bool
	// ReadOnly marks a knob that can be read but never set through PRAGMA.
	ReadOnly bool
	// Doc is the short cross-reference string shown in the configuration view.
	Doc string
}

Knob is one configuration parameter. The zero value is not useful; knobs are declared in the registry.

func All

func All() []Knob

All returns every knob in name order. The slice is a fresh copy, so callers may sort or filter it freely.

func Lookup

func Lookup(name string) (*Knob, bool)

Lookup resolves a knob by canonical name or alias, case-insensitively. The returned pointer is into the shared registry and must not be mutated.

func WithPrefix

func WithPrefix(prefix string) []Knob

WithPrefix returns the knobs whose name starts with prefix, in name order.

func (*Knob) Canonicalize

func (k *Knob) Canonicalize(raw string) (string, error)

Canonicalize parses raw against the knob's kind and range and returns the canonical string form stored in the catalog and returned by reads. A bad value returns a *ValueError describing the violation. The canonical form is stable: the same logical value always renders the same string, so a read after a set returns what the caller meant.

func (*Knob) IsEnum

func (k *Knob) IsEnum(v string) (string, bool)

IsEnum reports whether v is one of the knob's allowed enum tokens, matched case-insensitively. It returns the canonical-cased token on a match.

type Tier

type Tier int

Tier is a knob's mutability tier (spec 22 §1.1). It decides where the value lives and whether it can change after the file is created.

const (
	// TierCreate is fixed at create time in the file header; changing it needs a
	// dump and reload.
	TierCreate Tier = iota
	// TierPersistent survives reopen; it lives in the catalog page.
	TierPersistent
	// TierSession lasts for one Open call or connection; it never touches disk.
	TierSession
	// TierServer is a server-process knob, set from config or env at startup.
	TierServer
	// TierProcess is process-wide and set once (GOMAXPROCS, log level/format).
	TierProcess
)

func (Tier) String

func (t Tier) String() string

String renders the tier as the short code used in the configuration view.

type ValueError

type ValueError struct {
	Reason string
}

ValueError reports a raw value that a knob rejects. The vec package wraps it in the public ErrInvalidConfig type, carrying the knob name and the reason text.

func (*ValueError) Error

func (e *ValueError) Error() string