development.md

Build and test

Back to README

The native extension requires Rust, Bun (for smoke tests), CMake, Ninja, Git, and a C/C++ toolchain. The build scripts fetch pinned dependencies. No UI source checkout or frontend build is required.

Run the commands below from the repository root.

Community build

The DuckDB and extension-ci-tools submodules pin DuckDB 2.0.0 and its community build tooling. Initialize them before using the standard extension targets:

git submodule update --init --recursive
make setup-vcpkg
VCPKG_TOOLCHAIN_PATH="$PWD/vcpkg/scripts/buildsystems/vcpkg.cmake" GEN=ninja make release
make test

The SQL tests start the server with a small local UI fixture, exercise MCP owner isolation and shutdown, and verify invalid startup options and disabled external access. They install runtime dependencies from DuckDB's core repository; they do not need a Sidequery repository registration or the hosted UI.

The community workflow uses DuckDB's reusable distribution workflow for Linux x86-64/ARM64, macOS Intel/Apple Silicon, and Windows MSVC. Wasm cannot provide the native server's sockets and filesystem; Windows MinGW is not supported. The CI setup hook installs Boxington into the disposable workspace when another compiler wrapper is not already configured.

Rust tests

mbx test --manifest-path http/Cargo.toml --locked -- --test-threads=1

mbx is the Boxington compiler cache. If it is unavailable, use cargo in its place. The release build also runs the ignored deployed-UI check, which requires network access.

DuckDB 2.0 on macOS

Install Rust 1.99.0 through rustup, have Curl, Perl, and Make available, and supply the matching official DuckDB 2.0 CLI:

scripts/build-release.sh --duckdb /absolute/path/to/v2.0.0/duckdb

This builds Quack and SQLNB, runs Rust and native smoke tests, and writes artifacts to .artifacts/v2.0.0/<platform>/. See release builds for exact versions, prerequisites, and signing procedures.

For local testing on Apple Silicon, start that same CLI with -unsigned, then:

load '/absolute/path/to/sqlnb-extension/.artifacts/v2.0.0/osx_arm64/quack.duckdb_extension';
load '/absolute/path/to/sqlnb-extension/.artifacts/v2.0.0/osx_arm64/sqlnb.duckdb_extension';
select sqlnb_start();

Use osx_amd64 for Intel macOS. Unsigned loading is only needed for local build artifacts; installed releases use the signed repository.

Windows qualification

The Windows workflow runs the Rust contracts and filesystem security tests, then builds DuckDB 2.0, Quack, and SQLNB and exercises the native HTTP bridge. From a Visual Studio developer PowerShell with Rust 1.99.0, Bun, CMake, Ninja, and Git available:

./scripts/qualify-windows.ps1

The script uses a temporary build directory. The Rust security tests also require permission to create symbolic links, as configured by the workflow.

Legacy DuckDB 1.5.4 build

scripts/build-and-test.sh targets DuckDB 1.5.4, independently of the 2.0 release profile. It supports macOS and Linux, requires Python 3 in addition to the tools above, and retains a matching CLI and extensions:

bash scripts/build-and-test.sh
.artifacts/osx_arm64/duckdb -unsigned

Use the corresponding platform directory on Linux or Intel macOS. In that CLI:

load '/absolute/path/to/sqlnb-extension/.artifacts/osx_arm64/httpfs.duckdb_extension';
load '/absolute/path/to/sqlnb-extension/.artifacts/osx_arm64/quack.duckdb_extension';
load '/absolute/path/to/sqlnb-extension/.artifacts/osx_arm64/sqlnb.duckdb_extension';
select sqlnb_start();

Do not mix artifacts between DuckDB versions. The legacy sidequery_ui_start, sidequery_ui_status, and sidequery_ui_stop compatibility aliases remain available.

Working on the UI

UI source and build tooling live separately from this repository. On DuckDB 2.0, point the native server at a built frontend directory:

select sqlnb_start(assets := '/absolute/path/to/assets');

Local assets take precedence over the remote ui URL. See the asset contract for remote hosting and cache behavior.