Principle:Duckdb Duckdb Release Promotion
| Field | Value |
|---|---|
| sources | scripts/extension-upload-from-nightly.sh
|
| domains | Extension_Development, Release_Management |
| last_updated | 2026-02-07 |
Overview
Promoting validated artifacts from a staging environment to production for end-user consumption. This principle governs the staged release pattern where extension artifacts are first published to a nightly or staging bucket, tested for correctness, and then promoted (copied) to the production bucket that serves end users.
Description
Rather than uploading extensions directly to the production repository, DuckDB follows a staged deployment pattern where artifacts move through distinct environments before reaching end users:
Stage 1: Nightly / Staging
Extensions are uploaded to a nightly S3 bucket (e.g., s3://duckdb-extensions-nightly/) after being built and signed. This bucket serves as the staging environment where artifacts can be:
- Tested using the extension loading verification process
- Evaluated by developers and early adopters
- Held pending final approval before release
Stage 2: Verification
Extension loading tests are run against the nightly bucket to confirm that all extensions install, load, and function correctly. This step catches any issues introduced during the build, signing, or upload process that were not detected by earlier pipeline stages.
Stage 3: Promotion
Once verification passes, the artifacts are promoted by copying them from the nightly bucket to the production bucket (e.g., s3://duckdb-extensions/). This is a copy operation, not a rebuild, ensuring that the exact same bytes that were tested are the bytes that reach end users.
Why staged promotion matters:
- Immutable artifact guarantee -- the binary that was tested in staging is byte-for-byte identical to what is promoted to production. There is no risk of a "works on my machine" discrepancy caused by rebuilding.
- Rollback capability -- if issues are discovered after promotion, the nightly bucket retains the previous version and the production bucket can be restored from a known-good state.
- Decoupled pipelines -- the build/sign/upload pipeline and the promotion pipeline are independent, allowing different teams or automation systems to own each stage.
- Risk reduction -- by requiring successful verification before promotion, the pattern ensures that obviously broken artifacts never reach end users, even if earlier pipeline stages have bugs.
The promotion operation must handle:
- All platforms -- iterating over every supported platform directory and copying all extensions
- Version consistency -- ensuring that all platforms for a given version are promoted atomically (or at least completely)
- Idempotency -- re-running promotion for the same version and platform produces the same result
Usage
This principle applies after extension loading tests pass, to make extensions available to end users. It is the fifth and final step in the Extension Development and Distribution workflow.
Typical scenarios:
- A scheduled nightly job promotes the latest nightly build to the production bucket after tests pass
- A release manager manually triggers promotion for a tagged release version
- Hotfix releases are promoted immediately after targeted verification
Theoretical Basis
- Staged deployment -- a deployment strategy where artifacts progress through multiple environments (development, staging, production) with quality gates between each stage.
- Blue-green release patterns -- while DuckDB does not use a strict blue-green pattern, the nightly/production bucket separation provides a similar benefit: a known-good production environment is maintained while new artifacts are validated in a parallel environment.
- Immutable artifact promotion -- the principle that artifacts should be built once and promoted through environments, never rebuilt. This eliminates a class of bugs caused by non-reproducible builds.