Build a Reproducible DuckDB Analysis Bundle

Version scope: DuckDB 2.0 documentation.

Sending a SQL file is not enough to reproduce an analysis. The reviewer also needs to know what data it read, which environment interpreted it and how the author decided the result was acceptable. A compact analysis bundle makes those dependencies explicit without requiring a full platform project.

The goal is not to archive every byte indiscriminately. It is to preserve the smallest authorized set of artifacts that explains and reproduces the decision. Sensitive production data may require a controlled location or a synthetic fixture rather than an attachment.

Organize the bundle around a run

Use a run identifier and keep these artifacts together:

• A README containing the question, scope, expected inputs and run instructions.
• An input manifest containing immutable file identifiers, digests and schema versions.
• SQL files for preparation, analysis and assertions.
• An environment record containing engine, client and extension versions.
• A result manifest containing output digests, row counts and validation outcomes.
• A cleanup procedure that names only resources created by the run.

Keep source data credentials out of the bundle. A reviewer should receive access through an approved mechanism, not a secret embedded in a script or connection string. Sanitizing the README is insufficient if logs still contain signed URLs or query literals with sensitive values.

Make the assertions explain the answer

For an order analysis, assert more than a plausible total. Check input key uniqueness, expected date coverage, permitted currencies and the relationship between accepted and rejected rows. If the query drops records, count and explain them.

A useful assertion has a failure message that points to the violated contract. “Expected one currency, found three” is more actionable than “test failed.” Save summary diagnostics without exposing unnecessary row-level values.

Use a tiny synthetic fixture with deliberately difficult cases: duplicate keys, null values, a boundary timestamp and a late correction. State the expected output in the README. This makes review possible even when the real dataset cannot leave a restricted environment.

Capture the environment without overstating portability

Record the actual DuckDB version with the runtime's version facility and record the package lock or installation method used by the client. Document required extensions and the exact storage paths or logical identifiers. A query that relies on a local working directory should say so.

DuckDB can export data using SQL, including Parquet output. The resulting file can be one component of the bundle, but exporting data alone does not capture application semantics, source provenance or every environmental dependency. DuckDB Parquet export documentation

Different environments can also differ in time-zone data, available memory and filesystem behavior. Record those when they affect the analysis. Avoid promising byte-identical output across platforms unless the harness actually tests that property; logical equality and binary equality are distinct acceptance criteria.

Give the reviewer an independent path

The reviewer should start from a clean disposable directory, verify the input manifest, run the documented commands and inspect assertion outcomes. Do not rely on an author-created temporary table that is absent from the instructions.

Require an explicit final step that promotes a validated output. A failed run must not look identical to a successful one because an old output file remains in place. Use run-specific output paths and include the run identifier in the result manifest.

The procedures in this article are proposed review practices, not a completed execution record. Before relying on a bundle, build the fixture and run the full sequence from a clean environment, including cleanup and intentional assertion failures.

A good bundle turns an analytical answer into something another engineer can challenge. It preserves the question, evidence and acceptance criteria, so review does not depend on the author's memory or machine.

A reviewer combines the declared contract and fixed inputs in a clean run. An output file alone is not a reproducibility bundle.