Principle:Duckdb Duckdb Settings And Storage Info Generation

Overview

This principle covers generating configuration settings infrastructure and storage version constants from declarative specifications. DuckDB defines its database settings and storage format versions in JSON files, and Python code generators transform these into the C++ headers and source files that the engine consumes at compile time.

Description

The Settings and Storage Info Generation principle governs two related code generation tasks:

1. Configuration settings generation -- A code generator reads a JSON specification (src/common/settings.json) that declares each database setting with its name, description, SQL type, scope (global or local), and default value. From this single source of truth, the generator produces:
   • A C++ header declaring the settings classes (settings.hpp)
   • A C++ implementation file with the autogenerated settings logic (autogenerated_settings.cpp)
   • Scope registration entries in config.cpp
2. Storage version constant generation -- A separate code generator reads a version map JSON file (src/storage/version_map.json) and produces a C++ header (storage_info.hpp) containing version constants that the storage layer uses for format compatibility checks.

By auto-generating this infrastructure, the principle ensures that:

• Settings are consistently registered with the correct metadata (name, description, type, scope, default) across all consuming code paths.
• Storage version constants are derived from a single authoritative version map, eliminating the risk of version mismatches between different parts of the storage layer.
• Adding or modifying a setting requires only a JSON edit, not manual changes to multiple C++ files.

Usage

Apply this principle when adding new database settings or updating storage format versions:

• To add a new database setting, add an entry to src/common/settings.json specifying its name, description, sql_type, scope, and default_value, then re-run the settings generator.
• To update storage format versions (e.g., when the on-disk format changes), update src/storage/version_map.json and re-run the storage info generator.
• Both generators are invoked as part of the code generation pipeline to keep generated artifacts in sync with their declarative sources.

Theoretical Basis

• Declarative configuration management -- Settings are defined in a declarative JSON format rather than as scattered C++ registration calls. This makes the set of available settings easily auditable and ensures uniform treatment.
• Storage version compatibility tracking -- By maintaining a version map that is the single source of truth for storage format versions, the system can reliably detect format incompatibilities and provide meaningful error messages during upgrades or downgrades.

Related

Implementation:Duckdb_Duckdb_Generate_Settings