{"id":15667912,"url":"https://github.com/rupurt/duckdb-extension-template-zig","last_synced_at":"2025-05-06T19:47:48.335Z","repository":{"id":225020958,"uuid":"762917127","full_name":"rupurt/duckdb-extension-template-zig","owner":"rupurt","description":"A Zig template for building DuckDB extensions","archived":false,"fork":false,"pushed_at":"2024-03-16T21:10:24.000Z","size":11,"stargazers_count":28,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T02:21:57.672Z","etag":null,"topics":["c","cpp","duckdb","duckdb-extension","federated-query","zig"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rupurt.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-02-25T03:42:59.000Z","updated_at":"2025-02-01T16:01:59.000Z","dependencies_parsed_at":"2024-03-17T00:17:44.670Z","dependency_job_id":"1fd30c69-d0d5-4d5b-84b5-c03ae80b184c","html_url":"https://github.com/rupurt/duckdb-extension-template-zig","commit_stats":null,"previous_names":["rupurt/duckdb-extension-template-zig"],"tags_count":0,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupurt%2Fduckdb-extension-template-zig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupurt%2Fduckdb-extension-template-zig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupurt%2Fduckdb-extension-template-zig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rupurt%2Fduckdb-extension-template-zig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rupurt","download_url":"https://codeload.github.com/rupurt/duckdb-extension-template-zig/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252758030,"owners_count":21799766,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","cpp","duckdb","duckdb-extension","federated-query","zig"],"created_at":"2024-10-03T14:05:50.120Z","updated_at":"2025-05-06T19:47:48.300Z","avatar_url":"https://github.com/rupurt.png","language":"Nix","funding_links":[],"categories":["Extensions"],"sub_categories":["Other Extensions"],"readme":"# duckdb-extension-template-zig\n\nA Zig \u0026 Nix toolkit template for building extensions against multiple versions of DuckDB\nusing Zig, C or C++.\n\n## Usage\n\n```shell\n\u003e nix develop -c $SHELL\n\u003e duckdb -unsigned\nD LOAD 'zig-out/lib/quack.duckdb_extension';\nD FROM duckdb_extensions();\n┌──────────────────┬─────────┬───────────┬──────────────┬────────────────────────────────────────────────────────────────────────────────────┬───────────────────┐\n│  extension_name  │ loaded  │ installed │ install_path │                                    description                                     │      aliases      │\n│     varchar      │ boolean │  boolean  │   varchar    │                                      varchar                                       │     varchar[]     │\n├──────────────────┼─────────┼───────────┼──────────────┼────────────────────────────────────────────────────────────────────────────────────┼───────────────────┤\n│ arrow            │ false   │ false     │              │ A zero-copy data integration between Apache Arrow and DuckDB                       │ []                │\n...\n│ quack            │ true    │           │              │                                                                                    │ []                │\n...\n│ visualizer       │ true    │           │              │ Creates an HTML-based visualization of the query plan                              │ []                │\n├──────────────────┴─────────┴───────────┴──────────────┴────────────────────────────────────────────────────────────────────────────────────┴───────────────────┤\n│ 24 rows                                                                                                                                              6 columns │\n└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘\nD FROM duckdb_extensions();\n\u003e WHERE function_name ILIKE '%quack%';\n┌───────────────┬─────────────┬───────────────┬───────────────┬─────────────┬─────────────┬───┬─────────┬──────────────────┬──────────────────┬──────────┬──────────────┬─────────┐\n│ database_name │ schema_name │ function_name │ function_type │ description │ return_type │ … │ varargs │ macro_definition │ has_side_effects │ internal │ function_oid │ example │\n│    varchar    │   varchar   │    varchar    │    varchar    │   varchar   │   varchar   │   │ varchar │     varchar      │     boolean      │ boolean  │    int64     │ varchar │\n├───────────────┼─────────────┼───────────────┼───────────────┼─────────────┼─────────────┼───┼─────────┼──────────────────┼──────────────────┼──────────┼──────────────┼─────────┤\n│ system        │ main        │ quack         │ scalar        │             │ VARCHAR     │ … │         │                  │ false            │ true     │         1473 │         │\n├───────────────┴─────────────┴───────────────┴───────────────┴─────────────┴─────────────┴───┴─────────┴──────────────────┴──────────────────┴──────────┴──────────────┴─────────┤\n│ 1 rows                                                                                                                                                    14 columns (12 shown) │\n└─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘\nD SELECT quack('howdy');\n┌────────────────┐\n│ quack('howdy') │\n│    varchar     │\n├────────────────┤\n│ Quack howdy 🐥 │\n└────────────────┘\n```\n\n## How it Works\n\nDuckDB is a fast in-process analytical database written in C++ that can be extended by\ncreating and loading a dynamically linked library using the [extension API](https://duckdb.org/docs/extensions/overview.html). \nTypically extensions are written in C++ using the officially supported [extension template](https://github.com/duckdb/extension-template).\n\nBut you're one of the cool kids and want to write your extension in Zig! Fortunately the [Zig build system](https://ziglang.org/learn/build-system/)\nships with a Zig, C \u0026 C++ compiler. \n\n### 1. Create a project directory initialized with the multi flake template\n\nThe Nix environment generated by the `flake.nix` [template](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/templates/multi/flake.nix)\nprovides a self contained Linux \u0026 MacOS development toolchain:\n\n- Clang (16.0.6)\n- libcxx headers (16.0.6)\n- Zig `master` (0.12.0-dev.3247+26e895e3d)\n- Multiple `duckdb` CLI \u0026 `libduckdb` versions linked to the same versions of `libc` \u0026 `libcxx` as the Zig compiler (v0.10.0, v0.9.2 \u0026 main)\n\n```shell\n\u003e mkdir myextension \u0026\u0026 cd myextension\n\u003e nix flake init -t github:rupurt/duckdb-extension-template-zig#multi\n\u003e nix develop -c $SHELL\n```\n\n### 2. Implement 2 extension loader functions\n\nWhen a DuckDB extension is loaded via `LOAD 'myextension.duckdb_extension';` it requires [2 symbols](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/src/root.zig#L7C1-L13C2)\nto be defined (`myextension_version` \u0026 `myextension_init`). The value returned from `*_init` must\nmatch the version of DuckDB loading the extension.\n\nWe create a [simple header file](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/src/include/bridge.h) to\nexpose these 2 symbols in our built extension.\n\n### 3. Create a C++ bridge that calls `DuckDB::ExtensionUtil`\n\nThe extension utils helper plugs into DuckDB internals such as:\n\n- scalar functions\n- table functions\n- custom catalogs\n- much more...\n\nThe example in this repository [registers a simple scalar function](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/src/bridge.cpp#L26) called `quack`\n\n### 4. Configure the Zig build system and compile the extension\n\nThe Zig build system is configured in [build.zig](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/build.zig).\n\n- We'll need to add a [shared library](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/build.zig#L12) exposing\nthe DuckDB extension hooks defined in `root.zig`.\n- Add the [include](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/build.zig#L16) path for the\n[C header file](https://github.com/rupurt/duckdb-extension-template-zig/tree/main/src/include) exposing these hooks.\n- Don't forget the [C++ bridge](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/build.zig#L19)\n- By convention DuckDB extensions use the file suffix `.duckdb_extension`. Zig writes the dynamic library using \nthe format `libmyextension.[so|dylib|dll]`. Add a custom install step to use the DuckDB naming convention\nfor the [extension filename](https://github.com/rupurt/duckdb-extension-template-zig/blob/main/build.zig#L29).\n\n## Limitations\n\nCurrently this template can only build extensions using versions of `duckdb` provided by the [duckdb-nix](https://github.com/rupurt/duckdb-nix)\nflake. The derivation built by the flake includes header files for `duckdb` [third_party](https://github.com/duckdb/duckdb/tree/main/third_party)\ndependencies.\n\nI have opened a [Github issue](https://github.com/NixOS/nixpkgs/issues/292855) to include those libraries\nin the `nixpkgs` derivation.\n\n## Development\n\nThis repository assumes you have Nix [installed](https://determinate.systems/posts/determinate-nix-installer)\n\n```shell\n\u003e nix develop -c $SHELL\n\u003e nix develop .#v0-10-0 -c $SHELL\n\u003e nix develop .#v0-9-2 -c $SHELL\n\u003e nix develop .#main -c $SHELL\n```\n\n```shell\n\u003e make\n```\n\nRun the Zig test suite\n\n```shell\n\u003e make test\n```\n\nDelete artifacts from previous builds\n\n```shell\n\u003e make clean\n```\n\nBuild extension binary with Zig\n\n```shell\n\u003e make build\n```\n\nRun `duckdb` cli allowing `-unsigned` extensions\n\n```shell\n\u003e make run\n```\n\n## License\n\n`duckdb-extension-template-zig` is released under the [MIT license](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frupurt%2Fduckdb-extension-template-zig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frupurt%2Fduckdb-extension-template-zig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frupurt%2Fduckdb-extension-template-zig/lists"}