Skip to main content

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​

NumberWhere it is setWhat it means
The release the headers come fromlibduckdb-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 metadataTARGET_DUCKDB_VERSION in the Makefile, handed to append_extension_metadata.py as -dvRead as a C API version under abi_type = C_STRUCT, and as a release under C_STRUCT_UNSTABLE.
The engine that loads the filethe user's DuckDBIts 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 scalar bind / init slots, varargs, and the logical types DuckDB gained in 1.5 (today TIME_NS). duckfn groups all of it behind the duckdb-1-5 feature, which duck_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 (the sql feature) opens a connection from the database handle and goes through duckdb_query / duckdb_prepare / duckdb_bind_value / duckdb_fetch_chunk and 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 the duckdb-1-5 group even though the connection it borrows is the same one duck_vfs uses.

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_VERSION is a C API floor, not a release — that is what the mode buys. v1.2.0 is where DuckDB 1.3.2 through 1.5.5 all sit, so one artifact covers them (measured, below).
  • export QUACK_RS_TARGET_DUCKDB_VERSION is deliberately absent here, and adding it would not help. quack-rs reads that variable only in the unstable path: abi::check() returns StableOnly before it ever calls built_against_version(), whenever uses_unstable_api() — i.e. cfg!(feature = "duckdb-1-5") — is false.
  • DUCKDB_TEST_VERSION is 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)​

note

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_STRUCT here is a floor, not a release: v1.5.6 is 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 at LOAD (their C API version is v1.2.0). Build against the 1.5.6 headers (libduckdb-sys 1.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_VERSION may 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_API is only the metadata-ABI switch, not the capability switch: the capabilities come from the feature list. Leaving it at 0 is what makes the stamp C_STRUCT.
  • Do not export QUACK_RS_TARGET_DUCKDB_VERSION here. That variable declares which release the resolved headers came from; set it only when it matches libduckdb-sys, or quack-rs' runtime check reports a DeclaredVersionMismatch. With the pin above it is v1.5.6 and 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.0 while turning duckdb-1-5 on 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 declares v1.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 floorEngines that took the same binary
v1.2.01.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 configure builds configure/venv once and never refreshes the Python duckdb inside it (the recipe hangs off the directory, so a second make skips it), and a stale runner refuses a freshly built extension. Upgrade it in place — these are the two paths base.Makefile itself 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-sys changes 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​