pub struct Config {
pub storage: StorageConfig,
pub memory: MemoryConfig,
pub query: QueryConfig,
}Expand description
Main configuration structure for CQLite database.
§Every knob in #1696’s CENSUS is read or deleted — and the exception (#1696 roborev r5 F3)
Scoped to the census deliberately, because the unqualified version (“every
field here is read by something”) is contradicted by our own standing guard,
cqlite-core/tests/config_knob_behavior_guard.rs, which records every
CompressionConfig field as DECORATIVE with zero production readers.
What #1696 (epic #1685, “config honesty”) examined, it either kept because
something reads it, or DELETED: storage’s max_sstable_size /
block_size / enable_bloom_filters / bloom_filter_fp_rate /
io_threads / sync_mode, query’s plan_cache_size /
enable_optimization / parallel, and the entire performance tree are
gone — setting any of them changed nothing, silently.
The KNOWN exception is CompressionConfig (enabled / algorithm /
level / min_block_size). Those four were NOT in #1696’s census and are
deliberately left in place: the read path takes its algorithm from
CompressionInfo.db as the no-heuristics mandate requires, and the write
surface is uncompressed-only (#1406 owns that boundary and the
compressed-write wiring), so there is nothing for them to steer today. No dedicated
removal issue exists; they belong to the open epic #1685. The guard is the
authority on which fields are decorative — read it, do not read a claim of
universal coverage into this heading.
Deleting a field is deliberately a COMPILE error for an embedder writing Rust: that is the loudest signal available, and it is preferred over a field that keeps deserializing while doing nothing.
§But this is ALSO a deserialization surface (#1696 roborev F1)
Config derives Deserialize, and serde DISCARDS unknown fields — so a
caller who configures CQLite through JSON or a dict (the Python bindings’
bridge) gets no compile step and, before #1696’s F1 fix, no signal at all: a
pre-change document naming a deleted knob loaded successfully and was
silently ignored. The rule is stated at the layer where a knob is SET, so the
authoring surfaces report removed keys by name instead:
Self::from_json_str / Self::from_json_str_reporting_removed for this
crate’s JSON surface (see crate::config_removed_keys), and
cqlite_cli::config::removed_keys for the CLI’s file surface. Both use the
same posture — parse-and-ignore PLUS a named warning, never
deny_unknown_fields — because ONE posture crate-wide is the requirement,
and hard-failing would leave an existing caller with no migration path over
keys that never did anything.
§ENFORCED where, exactly — and the ONE surface that is not (#3520)
Those constructors are OPTIONAL, so they do not cover the serde boundary
itself: serde_json::from_str::<Config> / from_value::<Config> bypass them
and still DISCARD removed keys in SILENCE. Enforced surfaces are the CLI
config-file loader, the Python bindings entry points, and Rust field access (a
compile error, for Rust callers only). The unenforced one is a direct serde
deserialization by an embedder — issue #3520, scoped out of #1696
deliberately (roborev r2 F3) and pinned by
direct_serde_deserialization_is_the_unreported_surface. Nothing here should
be read as universal coverage.
The standing guard is cqlite-core/tests/config_knob_behavior_guard.rs:
every leaf field below must be registered there with either a set-knob →
assert-observable-difference test or an explicit reason why no observable
difference is expressible. A newly added pub field with neither FAILS that
test — which is the point, since “nobody asked whether this knob is read” is
how the removed ones accumulated.
Fields§
§storage: StorageConfigStorage engine configuration
memory: MemoryConfigMemory management configuration
query: QueryConfigQuery engine configuration
Implementations§
Source§impl Config
impl Config
Sourcepub fn from_json_str(json: &str) -> Result<Self>
pub fn from_json_str(json: &str) -> Result<Self>
Deserialize a JSON Config document, reporting every key #1696 REMOVED
that it still names.
§Why this exists (#1696 roborev F1)
Deleting a decorative field from this struct is a compile error for an
embedder writing Rust, which is the loudest signal available — but serde
DISCARDS unknown fields, so a JSON or dict authoring surface (the Python
bindings’ cqlite.open(path, config=...) bridge) silently accepted a
pre-change document naming performance, storage.block_size,
query.parallel and the rest, and ignored it. The rule #1696 states —
a removed knob must produce a LOUD signal at the layer where it is set —
was therefore false at exactly the layer that cannot get a compile error.
The posture matches the CLI’s file surface, crate-wide and deliberately:
parse-and-ignore PLUS a named warning, never deny_unknown_fields,
which would hard-fail a caller whose config predates the removal with no
migration path.
The warning is logged at WARN via tracing. A caller that must SURFACE it
(the bindings raise a Python UserWarning) or assert it wants
Self::from_json_str_reporting_removed.
§This constructor is OPTIONAL, so it does not enforce the rule
Config derives Deserialize, so an embedder can call
serde_json::from_str::<Config> directly and bypass this entirely — serde
then DISCARDS the removed keys in silence. Enforcement at the serde
boundary itself is issue #3520 (#1696 roborev r2 F3, scoped out
deliberately); do not read this constructor as universal coverage.
§Errors
The document is not valid JSON, or does not deserialize into a Config.
Note that Config is not #[serde(default)], so the document must be
COMPLETE. This does NOT run Self::validate — the caller owns validating
the config it finally uses, possibly after folding in overrides.
Sourcepub fn from_json_str_reporting_removed(
json: &str,
source: &str,
) -> Result<(Self, Option<String>)>
pub fn from_json_str_reporting_removed( json: &str, source: &str, ) -> Result<(Self, Option<String>)>
As Self::from_json_str, but RETURNS the removed-key warning instead of
logging it, labelled with source (e.g. "config dict").
§ORDER
The deserialize runs FIRST and the scan only on success, so this
constructor never returns a removed-key report for a document that did
not become a Config. Nothing is lost: serde drops the removed keys from
Config, but nothing drops them from the text they were read out of.
This ordering is a property of the RETURN SHAPE, not a precondition of the
text: since #1696 roborev r5 F1 the warning asserts nothing about whether
the load succeeds, precisely so that no placement of it can be wrong (see
crate::config_removed_keys::deprecation_warning).
§Errors
See Self::from_json_str.
Source§impl Config
impl Config
Sourcepub fn memory_optimized() -> Self
pub fn memory_optimized() -> Self
Create a configuration optimized for memory usage
Sourcepub fn performance_optimized() -> Self
pub fn performance_optimized() -> Self
Create a configuration optimized for performance