Managed DuckDB binary

Copy Markdown View Source

QuackDB can download and cache DuckDB's official CLI binary for local QuackDB.Server usage. This is opt-in: dependency compilation never downloads DuckDB.

Local server

children =
  QuackDB.Server.child_specs(
    server: [name: MyApp.DuckDB, duckdb: :managed],
    client: [name: MyApp.QuackDB]
  )

Omit duckdb: :managed to use duckdb from PATH, or pass a path explicitly:

{QuackDB.Server, duckdb: "/usr/local/bin/duckdb"}

You can also force a path globally:

export QUACKDB_BINARY_PATH=/usr/local/bin/duckdb

Explicit install

mix quackdb.install
mix quackdb.install --print-path

Managed binaries are cached under the user's cache directory. Override it with:

export QUACKDB_BINARY_CACHE_DIR=/opt/quackdb/duckdb
mix quackdb.install

or:

mix quackdb.install --cache-dir /opt/quackdb/duckdb

Version and checksum policy

QuackDB.Binary.default_version/0 is the DuckDB CLI version pinned by the current QuackDB release. QuackDB ships SHA256 checksums for that version and the supported targets returned by QuackDB.Binary.known_targets/0.

Other DuckDB versions must pass an explicit checksum:

mix quackdb.install --version 1.5.4 --sha256 SHA256_HEX

QuackDB.Binary.install(version: "1.5.4", sha256: "SHA256_HEX")

Target prefetching

The install task can prefetch a supported target without validating that binary on the current host:

mix quackdb.install --target linux-amd64 --cache-dir priv/quackdb-binaries

This is useful for CI cache priming or container image build steps. Runtime duckdb: :managed still chooses the current OS/architecture automatically.

Supported managed-download targets for the pinned version are:

  • linux-amd64
  • linux-arm64
  • osx-amd64
  • osx-arm64

Windows managed downloads are not supported yet. Use QUACKDB_BINARY_PATH or pass duckdb: "C:/path/to/duckdb.exe" on Windows until zip extraction and checksum coverage are added.