Development workflow

The day-to-day cycle for an external contributor.

1. Fork and branch

Fork duckdb/duckdb to your own account, then:

git clone git@github.com:<you>/duckdb.git
cd duckdb
git remote add upstream https://github.com/duckdb/duckdb.git
git fetch upstream
git checkout -b my-feature upstream/main

Rebase frequently — git fetch upstream && git rebase upstream/main — and resolve any conflicts before pushing.

2. Build a usable engine for development

make reldebug             # release + debug symbols + extra checks (recommended)
build/reldebug/duckdb     # CLI you'll use locally
build/reldebug/test/unittest   # test runner

make debug is much slower at runtime and useful only when you need GCC/Clang sanitizer output or extra assertions. make relassert (FORCE_DEBUG=1 make relassert) is the middle ground used by maintainers.

3. Write code

Follow patterns-and-conventions. Common gotchas:

• Use idx_t, not size_t.
• Use smart pointers; never new / delete.
• Add new public APIs to src/include/duckdb/... and place implementations in src/<area>/.
• Put new SQL functions in src/function/ for engine-built-ins, or in extension/core_functions/ for the bundled function library.
• New physical operators go in src/execution/operator/<area>/. New logical operators go in src/planner/operator/.

4. Add tests

Prefer SQL tests in test/sql/<area>/<your-test>.test. C++ tests live in test/api/ and are reserved for things SQL cannot express. See testing.

5. Format

make format-fix

Use the exact clang-format version pinned in CONTRIBUTING.md (11.0.1) to avoid spurious formatting churn:

pipx install clang-format==11.0.1
# or
python3 -m pip install --user clang-format==11.0.1

Black is used for Python files.

6. Run the tests on your fork's CI

The DuckDB CI is large (the main workflow is .github/workflows/Main.yml, ~63 KB). Triggering the full matrix on a maintainer's runner queue is expensive, so:

1. Push your branch to your fork.
2. Enable GitHub Actions on the fork.
3. Watch the workflows run.
4. If the workflows succeed, open a PR to duckdb/duckdb. If they fail, fix the issues first.

CI on the upstream repo is not run on draft PRs — see CONTRIBUTING.md and the workflow DraftPR.yml.

7. Open the pull request

Include in the description:

• A short summary of the change.
• The motivation: what bug it fixes, what feature it enables.
• Test coverage: which .test files exercise the change.
• Risk: storage compatibility, performance, etc.

Reference the related issue with Fixes #1234. Maintainers may ask for splits, additional tests, or different naming. Smaller, focused PRs review and merge much faster.

8. Address review feedback

Push fixup commits to your branch; the maintainer will squash on merge. Keep the PR rebased on upstream/main. If a make format-fix or make generate-files step is missed, CI will tell you.

After merge

• Pull the latest main into your fork before starting your next change.
• Watch nightly tests (.github/workflows/NightlyTests.yml) for the next 24 hours if your change touched performance-sensitive paths.

Storage compatibility

DuckDB guarantees that databases created with version N can be read by version N+1 (and ideally vice versa). If you modify the storage format:

• Update src/storage/storage_info.cpp and src/storage/version_map.json.
• Add fixtures to test/bwc/ so older formats stay readable.
• Run python3 scripts/test_storage_compatibility.py and python3 scripts/test_serialization_bwc.py locally.

The CrossVersion.yml workflow runs the same checks on CI.