DuckDB Extension Template for Zig

A template for creating DuckDB extensions in Zig

---

This is a DuckDB extension template for Zig that provides a starting point for creating DuckDB extensions in Zig programming language. It uses the DuckDB's extension API (C version) and supports multi-platform builds using Zig's cross-compilation features.

I'm sharing this template here in case it can be useful to others.

Features

• All build tasks can be managed using build.zig or Makefile (if you prefer GNU Make)
• Built-in support for cross-compilation (for Linux, macOS, and Windows; ARM and AMD)
• Very fast builds; no need to build DuckDB from source
• Built extensions are version-agnostic and work with DuckDB 1.2.0 and later

Important

The template is in early development, so bugs and breaking API changes are expected. Please use the issues page to report bugs or request features.

---

Getting Started

Prerequisites

• Zig 0.15.2
• Python 3
• DuckDB 1.2.0 or later (recommended for testing the extension)
• GNU Make (optional, for convenience)
• A C compiler
• Git

Quick Start

1. Clone the repository with submodules:

   git clone --recursive https://github.com/habedi/template-duckdb-extension-zig.git
   cd template-duckdb-extension-zig

2. Configure your extension name (optional):

   The template uses "extension" as the default name. To use your own name, either:

   • Set it in the Makefile:

     EXTENSION_NAME ?= my_custom_extension

   • Or pass it as a parameter:

     make build-all EXTENSION_NAME=my_custom_extension

   • Or use zig build directly:

     zig build build-all -Dextension-name=my_custom_extension

3. Build the extension:

   make build-all
   # Or with a custom name:
   make build-all EXTENSION_NAME=my_custom_extension

4. Run tests:

   zig build test
   zig build test-extension -Dextension-name=my_custom_extension

5. Try it interactively:

   zig build duckdb -Dextension-name=my_custom_extension

Configuration Variables

The build system supports several configurable variables:

• EXTENSION_NAME - Name of the extension (default: "extension")
• EXTENSION_API_VERSION - DuckDB Extension API version (default: "v1.2.0"; normally you don't need to change this)
• EXTENSION_VERSION - Your extension version (default: "v1.0.0")
• PLATFORM - Target platform (default: auto-detected)

Example:

make build-all \
  EXTENSION_NAME=my_extension \
  EXTENSION_API_VERSION=v1.2.0 \
  EXTENSION_VERSION=v2.0.0

For GitHub Actions, update the environment variables in .github/workflows/builds.yml:

env:
    EXTENSION_NAME: my_custom_extension
    EXTENSION_API_VERSION: v1.2.0
    EXTENSION_VERSION: v1.0.0

Available Commands

All build tasks are managed through zig build or make:

• make build or zig build - Build the extension
• make build-all or zig build build-all - Build with DuckDB metadata added to the extension
• make test or zig build test - Run unit tests
• make test-extension or zig build test-extension - Test with DuckDB
• zig build duckdb - Start an interactive DuckDB session (with the extension loaded)
• make clean or zig build clean - Clean build artifacts and unnecessary files
• zig build docs - Generate documentation (Zig API docs)
• make build-all-platforms - Build for all supported platforms (OSes and hardware architectures)

---

Documentation

• API Documentation - Run zig build docs and open docs/api/index.html

Project Structure

├── build.zig             # Zig build configuration
├── Makefile              # Wrapper around `zig build` that extends its functionality (optional)
├── src/
│   ├── lib.zig           # Main extension code
│   ├── lib_test.zig      # Unit tests for the extension
│   ├── extension.c       # C entry point for the extension
│   └── duckdb.zig        # DuckDB extension API (translated to Zig from C)
└── external/             # External depencies like Git submodules (extension API)

---

Contributing

See CONTRIBUTING.md for details on how to make a contribution.

License

This project is licensed under the MIT License (LICENSE or https://opensource.org/license/MIT).

Acknowledgements

• The logo is from SVG Repo with some modifications.