Project Scaffold

quack_rs::scaffold::generate_scaffold generates every file of a new DuckDB community extension project in Rust — Cargo.toml, Makefile, CI workflow, description.yml, an example function and its tests — from a single function call.


What it generates

my_extension/
├── Cargo.toml                          # cdylib + rlib crate, MSRV, dependencies, release profile
├── Makefile                            # delegates to cargo + extension-ci-tools
├── extension_config.cmake              # required by extension-ci-tools
├── src/
│   ├── lib.rs                          # entry point, example function, unit test
│   └── wasm_lib.rs                     # WASM staticlib shim
├── description.yml                     # community extension metadata
├── test/
│   └── sql/
│       └── my_extension.test           # SQLLogicTest for the example function
├── .github/
│   └── workflows/
│       ├── extension-ci.yml            # fast native CI: lint, tests, MSRV build
│       └── MainDistributionPipeline.yml  # every community platform, via extension-ci-tools
├── .gitmodules                         # extension-ci-tools submodule (pinned branch)
├── .gitignore
└── .cargo/
    └── config.toml                     # Windows CRT static linking

Usage

generate_scaffold returns paths relative to the project root (Cargo.toml, src/lib.rs, ...) and writes nothing itself. Join them under the directory the project should live in — writing them relative to the current directory would overwrite whatever Cargo.toml and src/lib.rs are already there.

use quack_rs::scaffold::{ScaffoldConfig, generate_scaffold};
use std::path::Path;

fn main() {
    let config = ScaffoldConfig {
        name: "my_extension".to_string(),
        description: "My DuckDB extension".to_string(),
        version: "0.1.0".to_string(),
        license: "MIT".to_string(),
        maintainer: "Your Name".to_string(),
        github_repo: "yourorg/duckdb-my-extension".to_string(),
        // `excluded_platforms` defaults to DEFAULT_EXCLUDED_PLATFORMS (see
        // "Excluded platforms" below). `target_duckdb_version`,
        // `use_unstable_c_api` and `git_ref` default to the stable-ABI
        // settings; see `concepts/abi.md`.
        ..ScaffoldConfig::default()
    };

    let files = generate_scaffold(&config).expect("scaffold generation failed");

    // Everything goes under ./my_extension/, never into the current directory.
    let root = Path::new(&config.name);
    for file in &files {
        let path = root.join(&file.path);
        if let Some(parent) = path.parent() {
            std::fs::create_dir_all(parent).unwrap();
        }
        std::fs::write(&path, &file.content).unwrap();
        println!("created {}", path.display());
    }
}

The repository's scaffold_to_dir example does the same from the command line:

cargo run --example scaffold_to_dir -- my_extension            # writes ./my_extension
# An extension using the duckdb-1-5* features: C_STRUCT, C API v1.5.6
cargo run --example scaffold_to_dir -- my_extension ../my_extension --c-api v1.5.6

--c-api v1.5.6 sets target_duckdb_version to v1.5.6: the binary loads into DuckDB 1.5.6 and 2.0.0. --unstable <release> (use_unstable_c_api) pins the binary to one DuckDB 1.x release instead, such as --unstable v1.5.5; DuckDB 2.0 cannot load such a binary, and the scaffold refuses a 2.x release there.


ScaffoldConfig fields

FieldTypeDescription
nameStringExtension name — must match [lib] name in Cargo.toml and description.yml
descriptionStringDescription for description.yml and the //! docs of src/lib.rs. Quoted and escaped, so :, # and quotes are fine; must not be empty, padded with whitespace, or contain control characters other than newline and tab
versionStringThe extension's version, also the Cargo package version — so it must be semver without a leading v (validate_semver): 0.1.0, not v0.1.0, 1.0 or a date stamp
licenseStringSPDX license identifier or expression (e.g., "MIT", "MIT OR Apache-2.0")
maintainerStringYour name or org, listed in description.yml — one non-empty line
github_repoString"owner/repo", in the characters GitHub allows
excluded_platformsVec<String>Platforms the community build skips, written to description.yml and the distribution workflow alike. Defaults to DEFAULT_EXCLUDED_PLATFORMS (Wasm and MinGW)
git_refStringrepo.ref — a commit hash (or tag), not a branch. Defaults to REF_PLACEHOLDER so it cannot be submitted unset
target_duckdb_versionStringWritten as TARGET_DUCKDB_VERSION in the Makefile. Without use_unstable_c_api, the C API version: DUCKDB_API_VERSION (v1.2.0, the default) or DUCKDB_API_VERSION_1_5_6 (v1.5.6) for an extension that enables duckdb-1-5 / duckdb-1-5-3 / duckdb-1-5-4; v1.5.6 pins libduckdb-sys to ~1.10506.0 and loads into DuckDB 1.5.6 and 2.0.0. With use_unstable_c_api, an exact DuckDB 1.x release such as v1.5.5
use_unstable_c_apiboolStamps C_STRUCT_UNSTABLE, pinning the binary to the one DuckDB 1.x release in target_duckdb_version. DuckDB 2.0 cannot load such a binary, and 2.x releases are refused. Defaults to false

Name validation

Extension names must satisfy all of:

  • Match ^[a-z][a-z0-9_]*$ (no hyphens: the entry point is <name>_init_c_api)
  • Not exceed 64 characters
  • Be globally unique on community-extensions.duckdb.org

Use vendor-prefixed names to avoid collisions: myorg_analytics, not analytics.

The scaffold generator checks the first two rules before generating any files and returns an error if the name breaks one. Uniqueness is yours to check.


After scaffolding

cd my_extension
git init
git submodule add -b v2.0-cyanoptera https://github.com/duckdb/extension-ci-tools.git extension-ci-tools
git add -A
git commit -m "Scaffold my_extension"
make configure
make release
make test

git submodule add is not optional in a new project: the scaffold writes .gitmodules, but git submodule update --init does nothing until the submodule has been added once (Pitfall P4). The generated Makefile stops with this command if the checkout is missing. -b v2.0-cyanoptera checks out the extension-ci-tools branch the generated MainDistributionPipeline.yml builds with (DISTRIBUTION_CI_TOOLS_REF, the branch for DISTRIBUTION_DUCKDB_VERSION v2.0.0; extension-ci-tools has no v2.0.0 branch), or your target_duckdb_version for an unstable-ABI build (-b v1.5.5, for example); the community build uses the branch for the DuckDB release it targets, so keep the submodule, .gitmodules and the workflow on the same one.

Commit before make configure. make configure writes the extension version into configure/extension_version.txt from git — the tag on HEAD, otherwise the short commit hash. With no commit, extension-ci-tools records git's error message instead, which overflows the 32-byte version field of the metadata footer, and DuckDB then refuses the file with Unknown ABI type for extension. The generated Makefile guards against this by using the Cargo package version (v0.1.0) while there is no commit, and make EXTENSION_VERSION=v0.1.0 configure sets one explicitly. If you configured before committing, run make clean_all configure after the first commit so the version comes from git.

The project declares rust-version (quack-rs's MSRV, 1.86.0; extension-ci-tools builds with Rust 1.97.1 for DuckDB 2.0, Wasm included) and uses resolver = "3", so cargo resolves dependencies that build on that release; the generated CI's msrv job checks it.

cargo test runs the generated unit test and make test runs test/sql/my_extension.test against a real DuckDB. Replace the example function in src/lib.rs with your own, give each new function a test in both places, and push to GitHub — CI runs automatically.


Excluded platforms

The community build compiles every extension for nine platforms with extension-ci-tools' _extension_distribution.yml: linux_amd64, linux_arm64, osx_amd64, osx_arm64, windows_amd64, windows_amd64_mingw, wasm_mvp, wasm_eh and wasm_threads. For DuckDB 2.0, osx_amd64 is opt-in in extension-ci-tools (built only if an extension asks for it), and DuckDB 2.1 drops the platform. The generated MainDistributionPipeline.yml calls the same workflow, so a platform that fails there fails in your own CI first.

excluded_platforms is written both as excluded_platforms in description.yml and as exclude_archs in that workflow, so the two always agree. It defaults to DEFAULT_EXCLUDED_PLATFORMS — the three Wasm targets and windows_amd64_mingw — which most build: cargo community extensions exclude: they need the emscripten and MinGW toolchains, which a Rust extension rarely builds with unchanged. To opt in, pass a shorter list (an empty one builds everything), or in a generated project remove the platform from both description.yml and exclude_archs, and let the distribution workflow prove it builds:

#![allow(unused)]
fn main() {
use quack_rs::scaffold::ScaffoldConfig;

// Build Wasm too; keep only MinGW excluded.
let config = ScaffoldConfig {
    excluded_platforms: vec!["windows_amd64_mingw".to_string()],
    ..ScaffoldConfig::default()
};
}

Validate individual platform names with quack_rs::validate::validate_platform, or a semicolon-delimited string (as used in description.yml) with quack_rs::validate::validate_excluded_platforms_str.