Documentation
¶
Overview ¶
Package version provides a registry of CockroachDB SQL features and the versions in which they were introduced (or removed).
The registry is pure metadata. It does not inspect SQL or AST nodes; that is the job of the AST inspector layered on top of it (see issue #84). The contract between the two layers is the feature tag — a stable, machine-readable string that identifies a SQL feature independent of how the parser represents it.
Tags are named for the user-facing feature ("regional_by_row"), not for the AST node ("create_table_locality_regional_by_row"), because a single feature may surface in multiple AST shapes (e.g. CREATE TABLE ... LOCALITY and ALTER TABLE ... SET LOCALITY). Naming by feature lets one registry entry cover every AST shape and produces warning messages a user will recognize.
Lifecycle: a Registry is constructed once via NewRegistry (or DefaultRegistry for the seeded set) and is immutable afterward. Concurrent readers are safe; there is no mutation API.
Index ¶
Constants ¶
const ( FeaturePLpgSQLFunctionBody = "plpgsql_function_body" FeatureTrigramIndex = "trigram_index" FeatureRegionalByRow = "regional_by_row" FeatureAlterChangefeed = "alter_changefeed" // v24.3 features. FeatureTriggers = "triggers" FeatureShowLogicalReplicationJobs = "show_logical_replication_jobs" FeatureLDRSkipSchemaCheck = "ldr_skip_schema_check" // v25.1 features. FeatureVectorIndex = "vector_index" FeatureRowLevelSecurity = "row_level_security" FeatureCheckExternalConnection = "check_external_connection" FeatureLDRBidirectional = "ldr_bidirectional" FeatureDoBlock = "do_block" FeatureReturnsTable = "returns_table" FeatureXATransactions = "xa_transactions" // v25.2 features. FeatureCreatePolicyIfNotExists = "create_policy_if_not_exists" FeatureRefreshMaterializedViewAsOf = "refresh_materialized_view_as_of_system_time" FeatureAlterVirtualClusterReplicationSrc = "alter_virtual_cluster_replication_source" // v25.3 features. FeatureShowCreateAllTriggers = "show_create_all_triggers" FeatureShowCreateAllRoutines = "show_create_all_routines" FeatureAlterTableLoggedUnlogged = "alter_table_logged_unlogged" FeatureGrantRevokeRoutines = "grant_revoke_routines" // v25.4 features. FeatureInspectCommand = "inspect_command" FeatureShowInspectErrors = "show_inspect_errors" FeatureLTreeType = "ltree_type" FeatureChangefeedDatabaseLevel = "changefeed_database_level" FeatureAlterExternalConnection = "alter_external_connection" // v26.1 features. FeatureShowJobsResolvedTimestamp = "show_jobs_resolved_timestamp" FeatureBackupStrictStorageLocality = "backup_strict_storage_locality" FeatureExecuteSchedule = "execute_schedule" FeatureCompositeTypeArrayFields = "composite_type_array_fields" // v26.2 features. FeatureCommitAndChain = "commit_and_chain" FeatureAlterTableEnableDisableTrigger = "alter_table_enable_disable_trigger" FeatureAlterIndexStorageParams = "alter_index_storage_params" FeatureShowStatementHints = "show_statement_hints" FeatureAlterTablePushStatistics = "alter_table_push_statistics" )
Feature tag constants. These are the stable identifiers the AST inspector (#84) emits when it recognizes a feature in parsed SQL. Adding a new tag means adding both a constant here and a matching Feature{Tag: ...} entry in DefaultRegistry; a test enforces that every exported constant is registered.
Variables ¶
This section is empty.
Functions ¶
func Inspect ¶
func Inspect(stmts statements.Statements, target string, reg *Registry) []output.Error
Inspect walks each top-level statement in stmts, detects any CockroachDB SQL features it recognizes, and returns one output.Error (Severity=WARNING, Code=CodeFeatureNotYetIntroduced) per detected feature whose Introduced version (per reg) is newer than target. Warnings are advisory: the parse / validate verdict is unchanged.
target must be in canonical form (post-output.ValidateTargetVersion): MAJOR.MINOR or MAJOR.MINOR.PATCH, no leading "v". An empty target returns nil so callers can invoke Inspect unconditionally without guarding on whether --target-version was supplied.
reg may be nil, in which case the package-level defaultRegistry (seeded from DefaultRegistry) is used. Tests pass an explicit registry to exercise hand-rolled features.
Each returned Error carries Context entries — feature_tag, feature_name, introduced, target — so agents can branch programmatically without parsing the human-readable Message.
Precondition: target has already been validated by the caller (the CLI does this in cmd/root via output.ValidateTargetVersion; the MCP surface does it in resolveTargetVersion). An unparseable target silently returns no warnings, mirroring Registry.Supports.
Types ¶
type Feature ¶
Feature describes a single CockroachDB SQL feature and the version range in which it is available.
Introduced and Removed are MAJOR.MINOR strings (e.g. "24.1") in the same canonical form produced by output.ValidateTargetVersion. Patch components are not stored: feature gating is a minor-release-grained concern, and recording patch noise would invite false positives for users who specify "25.4.3".
- Introduced == "" means "supported in every known version" (i.e. predates the registry's earliest entry of interest).
- Removed == "" means "still supported in current versions".
DocURL is optional and intended for warning messages emitted by the AST inspector in #84.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds an immutable set of Feature entries, indexed by tag for O(1) lookup. Build with NewRegistry or DefaultRegistry.
func DefaultRegistry ¶
func DefaultRegistry() *Registry
DefaultRegistry returns the seeded set of CockroachDB feature entries. The set is intentionally small; it will grow over time as the AST inspector learns to recognize more features.
func NewRegistry ¶
NewRegistry constructs a Registry from the given features.
It panics on misconfiguration so that registry mistakes surface at init time rather than as silent StatusUnknown results at query time. Specifically, it panics if any feature has an empty Tag, an empty Name, a duplicate Tag, an unparseable Introduced or Removed version, a non-empty Removed without a non-empty Introduced (the "removed but never introduced" shape is undefined), or a Removed version that is not strictly greater than Introduced.
func (*Registry) Lookup ¶
Lookup returns the Feature registered under tag, if any. The bool is false when the tag is not registered.
func (*Registry) Supports ¶
Supports reports whether the feature identified by tag is available in target. target is expected to be in canonical form (post-output.ValidateTargetVersion): MAJOR.MINOR or MAJOR.MINOR.PATCH, no leading "v". Comparison ignores the patch component — feature gating is a minor-release concern.
The returned Feature is the registered entry (zero value when status is StatusUnknown), so callers can build a warning message without a separate Lookup call.
If target itself is unparseable, Supports returns (StatusUnknown, zero Feature). Callers should validate target once at the boundary rather than relying on this fallback.
type Status ¶
type Status int
Status reports whether a feature is available in a given target version. Returned by Registry.Supports.
const ( // StatusUnknown means the queried tag is not registered. Callers // that treat unknown tags as "do not warn" should check for this // value explicitly rather than relying on a boolean. // // StatusUnknown is intentionally the zero value, as a deliberate // exception to the project convention of starting enums at one. // The zero value is load-bearing here: a Status read from an // uninitialized variable, or returned for an unrecognized tag, // must be safe to interpret as "do not warn." Renumbering would // silently turn unknown lookups into StatusSupported. StatusUnknown Status = iota // StatusSupported means the target version is at or after the // feature's Introduced version, and before any Removed version. StatusSupported // StatusNotYetIntroduced means the target version predates the // feature's Introduced version. The AST inspector turns this // into a "feature requires vX.Y+" warning. StatusNotYetIntroduced // StatusRemoved means the target version is at or after the // feature's Removed version. StatusRemoved )
Status values.
Source Files