Development

This document is for extension contributors — building QuackScale, updating DuckDB, and CI. Integrators should read GUIDE.md and AUTHENTICATION.md.

What QuackScale is

QuackScale is a DuckDB community extension embedding libtailscale so a DuckDB process can join a tailnet and reach the Quack HTTP protocol on tailnet addresses.

QuackScale does not reimplement Quack. It provides tailnet lifecycle SQL, a localhost forwarder for Quack clients, and helpers such as attach_ducklake.

DuckDB + quackscale + libtailscale
  → tailscale_up, tailscale_quack_forward, quack_uri, attach_ducklake
DuckDB + quack (core)
  → quack_serve, ATTACH, quack_query

Build

Prerequisites: C++17, cmake, ninja or make, Go 1.25+ (CGO), git submodules.

git clone --recurse-submodules https://github.com/quackscience/duckdb-quackscale.git
cd duckdb-quackscale
GEN=ninja make release

Artifacts:

• build/release/duckdb
• build/release/extension/quackscale/quackscale.duckdb_extension

Disable libtailscale (stub build):

make CMAKE_VARS="-DQUACKSCALE_WITH_TAILSCALE=OFF"

Docker Compose images build from source by default — see examples/Dockerfile and .dockerignore.

Repository layout

cmake/Libtailscale.cmake     Go c-archive build + Go 1.25.5 bootstrap
third_party/libtailscale/     git submodule
src/                          C++ extension (bridge, forwarder, attach_ducklake)
scripts/e2e/                  Compose entrypoint, bootstrap, verify-image
examples/                     Docker Compose two-node demo
duckdb/                       DuckDB submodule
extension-ci-tools/             Extension build makefile submodule

libtailscale integration

• Built with go build -buildmode=c-archive → libtailscale.a
• C API: tailscale_up, tailscale_dial, tailscale_close, etc.
• CMake option QUACKSCALE_WITH_TAILSCALE (default ON)
• Ubuntu Docker builder needs build-essential and patch for the libtailscale patch step

Updating DuckDB

When bumping the DuckDB target:

1. Update ./duckdb submodule to the latest stable tag
2. Update ./extension-ci-tools to the branch matching that DuckDB version (e.g. v1.5.5)
3. Update duckdb_version in MainDistributionPipeline.yml
4. Rebuild — the DuckDB C++ API is not stable; fix compile breaks using release notes and core extension patches

CI workflows

Workflow	Trigger	Purpose
headscale-e2e.yml	Manual only	Release-binary two-node e2e (no source build)
headscale-integration.yml	PR	Source build + Headscale smoke
Release.yml	Release published / manual	Extension repo → GitHub Pages; linux QuackTail tarball → Releases
libtailscale-integration.yml	PR	libtailscale go test
MainDistributionPipeline.yml	PR	Extension distribution CI

E2e never runs on push/PR and never compiles DuckDB in CI — use workflow_dispatch on headscale-e2e with a release tag. Full DuckLake compose demo is local dev only (scripts/ci_compose_e2e.sh).

Release and GitHub Pages

On Release published (or manual Release workflow):

1. build — extension-ci-tools matrix (quackscale per platform, same exclusions as MainDistributionPipeline).
2. package-pages + deploy-pages — unsigned .duckdb_extension.gz under v1.5.5/{arch}/ at https://quackscience.github.io/duckdb-quackscale.
3. build-quacktail-bundle — linux amd64 quacktail-linux-amd64-{tag}.tar.gz attached to the GitHub Release.

One-time repo setup: Settings → Pages → Build and deployment → Source: GitHub Actions.

Manual Pages-only test: Actions → Release → Run workflow → leave release_tag empty, uncheck skip_pages.

Manual tarball test: provide an existing git tag in release_tag, uncheck skip_tarball.

Each Pages deploy replaces the whole site (one DuckDB version hosted). To host multiple DuckDB versions, accumulate version directories in a follow-up change.

Roadmap (selected)

Item	Status
tailscale_up, tailscale_quack_forward, tailscale_down	Done
attach_ducklake (Tier 2 remote lake views)	Done
Headscale + Compose e2e	Done
ATTACH … TYPE quacktail_lake (Tier 3 native catalog)	Planned
ducklake_discover() enriched discovery	Planned
quackscale_serve() one-call server bootstrap	Planned
Community extension descriptor publish	Done (GitHub Pages on release)

Risks

Risk	Mitigation
Large binary (Go runtime)	Document size; QUACKSCALE_WITH_TAILSCALE=OFF stub
Quack API churn	Pin DuckDB; integration tests against pinned quack
Secrets in SQL	Env / orchestrator secrets — see AUTHENTICATION.md

Tests

make test

SQL unit tests do not require a live tailnet. E2e: test/e2e/README.md, examples/README.md.

License

MIT (extension template). libtailscale is BSD-3-Clause.