Version numbers and the ABI
A duckfn extension never links DuckDB: it calls through the C API's function table, and DuckDB itself
decides at LOAD time whether the file is acceptable. Three different numbers take part in that
decision, and only one of them is the "DuckDB version" people usually mean. Which side you take on
each of them is what decides whether one build serves a range of DuckDB releases or exactly one.
The three numbers
| Number | Where it is set | What it means |
|---|---|---|
| The release the headers come from | libduckdb-sys in Cargo.toml (resolved in Cargo.lock) | Which duckdb_extension.h the build compiles against — the API surface your code may call. |
| The value written into the metadata | TARGET_DUCKDB_VERSION in the Makefile, handed to append_extension_metadata.py as -dv | Read as a C API version under abi_type = C_STRUCT, and as a release under C_STRUCT_UNSTABLE. |
| The engine that loads the file | the user's DuckDB | Its own C API level (or release) is what your declaration is checked against. |
The workflow's duckdb_version — and the DUCKDB_VERSION it also exports — is a fourth, unrelated
knob: it picks which DuckDB source the distribution pipeline checks out, which engine the
sqllogictest run uses, and what the artifacts are named. It never reaches your extension.
C_STRUCT vs C_STRUCT_UNSTABLE
USE_UNSTABLE_C_API in the Makefile decides which of the two ABI types the metadata claims, and
that is what makes the -dv value mean two different things.
USE_UNSTABLE_C_API=0 → abi_type = C_STRUCT. The declaration is a floor, and the loader
compares C API versions:
The file was built for DuckDB C API version '<declared>', but we can only load extensions built for
DuckDB C API '<engine>' and lower.
An engine whose C API is at or above your floor loads the file; its exact release does not matter. That is the portability you want, and it costs nothing as long as your code stays inside the stable region of the C API.
USE_UNSTABLE_C_API=1 → abi_type = C_STRUCT_UNSTABLE. Now the declaration is a release and
the engine demands a literal match. The unstable part of the extension API is a C struct addressed by
slot order, so a build compiled against a different set of slots cannot run: one file, one engine.
append_extension_metadata.py's own help text spells the split out: "The DuckDB version to encode,
depending on the ABI type this encodes the duckdb version or the C API version."
Where the values come from
Two files carry the settings — the headers come from Cargo.toml, the declaration from the
Makefile:
# Cargo.toml — the headers
libduckdb-sys = { version = ">=1.10500, <2", features = ["loadable-extension"] }
libduckdb-sys encodes a DuckDB release as 1.<major*10000 + minor*100 + patch>.0, so 1.10506.0
is DuckDB 1.5.6, 1.20000.0 is DuckDB 2.0.0, and the >=1.10500 above means "DuckDB 1.5 headers or
newer" — which includes 2.0. In the 2.0 generation the v1 bindings moved under libduckdb_sys::v1
(re-exported at the crate root as well) behind the default capi-v1 feature, so code that names
those items should be checked when you move; quack-rs 0.19 added 2.0 to its layout table, so the
wrapper no longer holds the range back. The checked-in Cargo.lock files of duckfn and the five
extensions now resolve 1.20000.0 (2.0 headers) on the stable capi-v1 surface; the range itself is
unchanged so a downstream crate can still resolve older headers.
Nothing else rewrites the Makefile line: ci-tools' set_duckdb_version is a no-op for C API
extensions, and the community registry's duckdb_version only chooses which DuckDB source to check
out, how the artifacts are named and which version directory they are deployed into. It is yours to
maintain — see Build and release. The next section gives both
complete sets.
Choosing for your own extension
One question decides it: does your code touch the unstable region?
- It holds copy functions, the host file system (
duckfn::duck_vfs), the scalarbind/initslots,varargs, and the logical types DuckDB gained in 1.5 (todayTIME_NS). duckfn groups all of it behind theduckdb-1-5feature, whichduck_vfs(the host VFS) depends on. - Everything else is in the stable region: scalars, aggregates, table functions, casts, replacement
scans, SQL macros, named STRUCT / ENUM types, the chrono / uuid / rust_decimal bridges, and
running SQL —
duckfn::sql(thesqlfeature) opens a connection from the database handle and goes throughduckdb_query/duckdb_prepare/duckdb_bind_value/duckdb_fetch_chunkand the logical types, none of which sit in the unstable region. That is deliberate: a callback-side capability is exactly where one binary across releases pays off, so it is kept out of theduckdb-1-5group even though the connection it borrows is the same oneduck_vfsuses.
Stable region — the complete set
# Makefile
EXTENSION_NAME=my_extension
USE_UNSTABLE_C_API=0
TARGET_DUCKDB_VERSION=v1.2.0
# Cargo.toml — the ABI point is that `duckdb-1-5` stays off (`cli` is only for the
# `function_descriptions` bin and has nothing to do with the ABI; `sql` is
# callback-side but stable, and keeps this set portable).
duckfn = { version = "0.3.1", features = ["cli", "sql"] }
# .github/workflows/MainDistributionPipeline.yml
duckdb_version: v2.0.0 # any engine at or above the floor; the newest is the safe pick
TARGET_DUCKDB_VERSIONis a C API floor, not a release — that is what the mode buys.v1.2.0is where DuckDB 1.3.2 through 1.5.5 all sit, so one artifact covers them (measured, below).export QUACK_RS_TARGET_DUCKDB_VERSIONis deliberately absent here, and adding it would not help. quack-rs reads that variable only in the unstable path:abi::check()returnsStableOnlybefore it ever callsbuilt_against_version(), wheneveruses_unstable_api()— i.e.cfg!(feature = "duckdb-1-5")— is false.DUCKDB_TEST_VERSIONis absent for the same reason: the test runner may be any newer engine, because every engine at or above the floor accepts the artifact.
Unstable region — the complete set (DuckDB 1.5.6 and 2.0.0)
quack-rs 0.19 changed how an unstable-region build is stamped: use C_STRUCT with a v1.5.6 C API
floor, not C_STRUCT_UNSTABLE. DuckDB 2.0 keeps the v1 C API at version v1.5.6 and only appends two
slots to the 1.5.6 layout, so a build against the 1.5.6 headers is accepted by both 1.5.6 and 2.0.0,
and quack-rs' runtime layout check accepts the appended layout. C_STRUCT_UNSTABLE is no longer the
route for new builds: DuckDB 2.0 sends every such binary to the C API v2 entrypoint
<name>_init_c_api_v2, which quack-rs does not generate, so it fails to LOAD there.
# Makefile
EXTENSION_NAME=my_extension
USE_UNSTABLE_C_API=0
TARGET_DUCKDB_VERSION=v1.5.6
DUCKDB_TEST_VERSION := 2.0.0
# Cargo.toml
duckfn = { version = "0.3.1", features = ["duckdb-1-5"] } # + "duck_vfs" for duckfn::duck_vfs (also in the unstable region)
libduckdb-sys = { version = "=1.10506.0", features = ["loadable-extension"] } # the 1.5.6 headers
# .github/workflows/MainDistributionPipeline.yml
duckdb_version: v2.0.0 # any engine at or above the floor; the newest is the safe pick
- The header pin is what buys the range.
C_STRUCThere is a floor, not a release:v1.5.6is the layout DuckDB 2.0 still runs, so one artifact covers 1.5.6 and 2.0.0 while 1.5.0 – 1.5.5 refuse it atLOAD(their C API version isv1.2.0). Build against the 1.5.6 headers (libduckdb-sys1.10506.x). A build against the 2.0 headers carries the 548-slot layout instead and is 2.0-only — quack-rs refuses the 546-slot engine rather than dispatch into the wrong slots. DUCKDB_TEST_VERSIONmay be any engine at or above the floor, so the newest one is the useful pick; the test-runner engine and the artifact no longer have to match literally.USE_UNSTABLE_C_APIis only the metadata-ABI switch, not the capability switch: the capabilities come from the feature list. Leaving it at 0 is what makes the stampC_STRUCT.- Do not export
QUACK_RS_TARGET_DUCKDB_VERSIONhere. That variable declares which release the resolved headers came from; set it only when it matcheslibduckdb-sys, or quack-rs' runtime check reports aDeclaredVersionMismatch. With the pin above it isv1.5.6and harmless, but the 1.5.6 and 2.0.0 layouts are already in its table, so it adds nothing.
The trap that survives: the declared floor has to match the headers you built against.
- Declaring
v1.2.0while turningduckdb-1-5on would be accepted by 1.5.0 – 1.5.5, whose unstable layout differs. quack-rs' runtime layout check refuses those engines, but do not rely on that check as the only gate — an unstable-region build declaresv1.5.6, the version whose layout it compiled against.
What a stable build actually covers
v1.2.0 is the C API level DuckDB 1.3.2 through 1.5.5 all sit at, so one stable build declaring it is
accepted across the whole range. Measured with a single artifact, each engine loading it and running a
real call:
| Declared C API floor | Engines that took the same binary |
|---|---|
v1.2.0 | 1.3.2, 1.4.0, 1.4.5, 1.5.0, 1.5.5, 1.5.6, 2.0.0 |
That table began as a one-off measurement and is now checked on every pull request:
.github/workflows/StableApiPipeline.yml builds an artifact with the settings above
(USE_UNSTABLE_C_API=0, TARGET_DUCKDB_VERSION=v1.2.0, EXTENSION_FEATURES=quack,sql) and runs the
stable subset of the suite against 1.3.2, 1.4.5, 1.5.6 and 2.0.0. The newest of the four is the control —
if that leg fails too, the stable build itself broke rather than the version range.
DuckDB 2.0 is out, and a stable build declaring v1.2.0 loads and runs there — verified by loading
such an extension into a 2.0 engine and calling its functions (an aggregate and a scalar both
returned the expected values). The floor is what buys that portability: do not read "runs on 2.0" as
"was compiled against 2.0".
One 2.0 naming trap: DuckDB ships a second, v2 C API (duckdb_v2.h) — a genuinely different,
still-rapid surface that the experimental duckdb-neo wrapper targets. It does not replace the v1
API for extensions: a loadable extension builds on the v1 C API (libduckdb-sys's default capi-v1
feature, required by loadable-extension), and that v1 surface is exactly what 2.0 still loads. So "C
API v2 is different" is about the new header, not about v1 extensions losing compatibility. Mind the
version encoding too: DuckDB 2.0.0 maps to a libduckdb-sys crate version 1.20000.x (format
1.<major*10000 + minor*100 + patch>.x) — still a 1.x, so a >=1.10500, <2 constraint selects it.
The <2 bound is not the blocker: quack-rs 0.19 added DuckDB 2.0 to its layout table (including the
v1.5.6 build running on 2.0's appended layout), so what remains is the bindings' new
libduckdb_sys::v1 path and your own code — and, only if you still stamp C_STRUCT_UNSTABLE, the v2
entrypoint, which quack-rs does not generate.
Raise the floor only when you genuinely need newer headers. And raise it by the C API version, not
by a release number: with C_STRUCT, v1.5.6 leaves 1.5.6 and 2.0.0 willing to take the file (the
layout they share), while v1.6.0 would wait for an engine that declares it.
Checking a build yourself
make debug prints the metadata it just wrote, which is the quickest way to see what you actually
declared rather than what you meant to:
FIELD2 = windows_amd64
FIELD3 = v1.2.0 # the declared version
FIELD5 = C_STRUCT # the ABI type
Then take that one artifact and load it into several engines — a locally built extension always needs
-unsigned:
duckdb -unsigned -c "LOAD '<path>/my_extension.duckdb_extension'; SELECT my_greet('world');"
Two traps come up here:
- A pinned test runner is not the engine under test.
make configurebuildsconfigure/venvonce and never refreshes the Pythonduckdbinside it (the recipe hangs off the directory, so a secondmakeskips it), and a stale runner refuses a freshly built extension. Upgrade it in place — these are the two pathsbase.Makefileitself uses:
configure/venv/Scripts/python.exe -m pip install --upgrade "duckdb==2.0.0" # Windows
configure/venv/bin/python3 -m pip install --upgrade "duckdb==2.0.0" # Linux / macOS
- The header pin and the engine are separate. Updating
libduckdb-syschanges what you may call, not what will load you — and vice versa.
WebAssembly (loading)
The same rules apply, with one extra caveat: the engine is fixed inside the DuckDB-Wasm bundle, so
you cannot pick it at LOAD time. An unstable build therefore has to be served by the exact dev build
carrying the matching release, while a stable build only needs an engine at or above its floor. How
this site pins that build is in Preloaded extensions.
How the wasm_* artifacts are built — the Rust the CI installs, the emsdk/binaryen it pins, and the
ci-tools ref they come from — is a different version story, covered in
The wasm build toolchain.
Release assets vs the community registry
LOAD '<url of a release asset>' fetches exactly the file you name, so "one binary across releases"
is entirely your declaration's doing. The community registry works differently: it hands out the
build for the DuckDB version the client reports, from a directory tree the registry fills in itself
— see Community extension docs. That makes the registry route
version-directed rather than version-tolerant, whatever you declared.
See also
- The wasm build toolchain — the Rust / emsdk / ci-tools version coupling behind
wasm_*. - Rust unwinding on WebAssembly — why
panic!behaves differently by Rust version. - Installation — what each duckfn feature requires of DuckDB.
- File system and Copy functions — the two capabilities that live in the unstable region.
- Running SQL from an extension — the one callback-side capability that stays in the stable region, and why that keeps the artifact portable.
- Build and release — the build paths and the release flow.
- Known issues — upstream bugs that are not about versions.