duckdb-go-bindings

This repository wraps DuckDB's C API calls in Go native types and functions.

Minimum Go version: 1.24.

🚧 WORK IN PROGRESS 🚧

Important

Some type aliases and function wrappers are still missing.

Breaking changes can happen.

Releases

Semantic versioning

Starting with DuckDB v1.5.0 the duckdb-go-bindings package changes its versioning scheme to contain

• the DuckDB release version
• the duckdb-go-bindings patch iteration

For v1.5.0 the corresponding tagged release is v0.10500.0.

Single module (v0.3.0+)

Starting with v0.3.0, the module includes pre-built static libraries for all platforms. Simply import github.com/duckdb/duckdb-go-bindings.

duckdb version	module version
v1.4.5	v0.3.5
v1.4.4	v0.3.4
v1.4.3	v0.3.0

Legacy per-platform submodules (v0.1.x)

Older versions require platform-specific imports (e.g., github.com/duckdb/duckdb-go-bindings/darwin-arm64). These tags continue to work.

duckdb version	main	darwin	linux	windows
v1.4.3	v0.1.24	v0.1.24	v0.1.24	v0.1.24
v1.4.2	v0.1.23	v0.1.23	v0.1.23	v0.1.23
v1.4.1	v0.1.21	v0.1.21	v0.1.21	v0.1.21
v1.4.0	v0.1.19	v0.1.19	v0.1.19	v0.1.19
v1.3.2	v0.1.17	v0.1.12	v0.1.12	v0.1.12
v1.3.1	v0.1.16	v0.1.11	v0.1.11	v0.1.11
v1.3.0	v0.1.15	v0.1.10	v0.1.10	v0.1.10
v1.2.2	v0.1.14	v0.1.9	v0.1.9	v0.1.9
v1.2.1	v0.1.13	v0.1.8	v0.1.8	v0.1.8
v1.2.0	v0.1.10	v0.1.5	v0.1.5	v0.1.5

Installation

Simply import the module in your Go project:

import "github.com/duckdb/duckdb-go-bindings"

The module includes pre-built static libraries for all supported platforms:

• darwin-amd64
• darwin-arm64
• linux-amd64
• linux-arm64
• windows-amd64

Platform detection and linking is handled automatically through cgo directives. CGO_ENABLED=1 is required, and your system needs a C compiler.

Local Development

To develop locally, copy the workspace template file:

cp go.work.dev go.work

This sets up Go workspaces to use the local lib/* submodules instead of fetching from the module proxy.

Nightly artifact validation

The Nightly workflow accepts a full DuckDB commit SHA and downloads the matching Linux, macOS, and Windows artifacts from DuckDB's staging endpoint. It compiles the bindings against the artifact header, summarizes the resulting header diff, exercises both static and dynamic linking, verifies the linked source ID, and installs and loads httpfs from a clean extension directory.

Releasing a new DuckDB version

Prepare normal releases from main. For LTS releases that stay on DuckDB 1.4 Andium, use the v1.4-andium branch.

1. Create a new branch and update the DUCKDB_VERSION in the Makefile.
2. Invoke the Fetch and Push Libs workflow on the new branch (it commits fetched libs to the branch; it does not tag).
3. If the header (duckdb.h) has changes, add all changes (new types, functions, etc.) to the bindings.
4. Open a PR.
5. Wait for all tests to pass.
6. Merge the PR into main (direct pushes to main are not allowed).
7. Publish tags using the release script (re-entrant, safe to run multiple times):

./scripts/release.sh v0.10502.0           # pushes to 'origin'
./scripts/release.sh v0.10502.0 upstream  # pushes to custom remote

The script handles:

• Tagging and pushing lib/* submodules
• Updating root module deps (stops for PR if changes needed)
• Tagging and pushing root module

Run it again after merging the deps PR to complete the release.

Build Configuration

Default: Pre-built Static Libraries

By default (no build tags needed), the module automatically links against the pre-built static libraries for your platform:

go build  # Just works!
go test   # Just works!

The appropriate library and linker flags are selected automatically based on your OS and architecture.

Alternative: Custom Static Libraries

To use your own DuckDB static library instead of the pre-built ones, use the duckdb_use_static_lib build tag and provide library paths via CGO_LDFLAGS:

# Darwin/macOS
CGO_ENABLED=1 \
  CPPFLAGS="-DDUCKDB_STATIC_BUILD" \
  CGO_LDFLAGS="-lduckdb -lc++ -L/path/to/lib" \
  go build -tags=duckdb_use_static_lib

# Linux
CGO_ENABLED=1 \
  CPPFLAGS="-DDUCKDB_STATIC_BUILD" \
  CGO_LDFLAGS="-lduckdb -lstdc++ -lm -ldl -L/path/to/lib" \
  go build -tags=duckdb_use_static_lib

# Windows
CGO_ENABLED=1 \
  CPPFLAGS="-DDUCKDB_STATIC_BUILD" \
  CGO_LDFLAGS="-lduckdb -lws2_32 -lwsock32 -lrstrtmgr -lstdc++ -lm --static -L/path/to/lib" \
  go build -tags=duckdb_use_static_lib

Alternative: Dynamic Libraries

To link against a shared DuckDB library, use the duckdb_use_lib build tag:

# Darwin/macOS
CGO_ENABLED=1 \
  CGO_LDFLAGS="-lduckdb -L/path/to/dir" \
  DYLD_LIBRARY_PATH=/path/to/dir \
  go build -tags=duckdb_use_lib

# Linux
CGO_ENABLED=1 \
  CGO_LDFLAGS="-lduckdb -L/path/to/dir" \
  LD_LIBRARY_PATH=/path/to/dir \
  go build -tags=duckdb_use_lib

Arrow functions

Provide the duckdb_arrow build tag if you want to use arrow functions