Entwicklung von Community-Erweiterungen

Bauen

DuckDB stellt ein C++-basiertes Extension Template bereit, das alles Nötige mitbringt. Das Template ist mit dem Paketmanager vcpkg, einem SQL-basierten Test-Framework und einer auf GitHub Actions basierenden CI/CD-Toolchain konfiguriert. Die CI/CD-Kette baut Ihre Erweiterung automatisch für alle unterstützten DuckDB-Plattformen, darunter Linux, macOS, Windows und Wasm.

Veröffentlichen

Um eine Erweiterung im DuckDB-Community-Repository zu veröffentlichen, kann ein Pull Request im Community-Repository geöffnet werden. Im Pull Request muss eine Deskriptordatei angegeben werden, die alle relevanten Informationen zur Erweiterung enthält, etwa das Quell-Repository und die Version. Schauen Sie sich die bereits vorhandenen Community-Erweiterungen als Beispiele an.

Das Community-Repository baut Erweiterungen mit DuckDBs CI-Toolchain. Das bedeutet, dass Ihre Erweiterung mit dieser Toolchain baubar sein muss. Glücklicherweise ist das genau dieselbe Toolchain, die das Extension Template verwendet; für Erweiterungen auf Basis des Templates funktioniert das daher ohne weiteres Zutun.

Entwicklerdokumentation

Da DuckDBs Community-Erweiterungen eine vergleichsweise neue Ergänzung des DuckDB-Ökosystems sind, gibt es derzeit nur begrenzte Entwicklerdokumentation. Informationen finden Sie an folgenden Stellen:

• READMEs im DuckDB-Repository
• CI-Toolchain
• Extension Template
• Community-Extensions-Repository

Dank des vollständigen Extension Templates und der großen Zahl an Beispielerweiterungen sollte die Entwicklung von Erweiterungen jedoch vergleichsweise unkompliziert sein.

Eine Erweiterung über DuckDB-Releases hinweg pflegen

Derzeit sollen Community-Erweiterungen nur für die jeweils neueste stabile DuckDB-Version gebaut und verteilt werden. Das bedeutet, dass Nutzer auf jeder anderen als der neuesten stabilen Version Community-Erweiterungen als eingefroren wahrnehmen, ohne weitere Updates.

Wenn das nächste DuckDB-Release näher rückt (siehe den Release-Kalender), wechselt das Repository duckdb/community-extensions dazu, Erweiterungen sowohl gegen die neueste stabile Version als auch gegen den aktuellen Branch main zu testen. Ist eine Erweiterung sowohl mit der neuesten stabilen Version als auch mit dem aktuellen Branch main kompatibel, sollte die Erweiterung vom neuen Release nicht betroffen sein. Das ist hoffentlich der Normalfall.

Ist eine Erweiterung nicht gleichzeitig mit beiden Branches kompatibel, ist der empfohlene Weg zur Aktualisierung der folgende:

1. Legen Sie zwei getrennte Branches an, einen für die neueste stabile Version und einen für den Branch main.
2. Geben Sie den Hash des neuesten Commits auf dem Branch für die stabile Version als ref an und den des Branches für main als ref_next.
3. So kann die Erweiterung sowohl gegen die neueste stabile Version als auch gegen das aktuelle main getestet werden.
4. Sobald ein Release-Hash feststeht, werden Community-Erweiterungen für diesen DuckDB-Hash gebaut, und ref_next (falls vorhanden) wird gegen ref ausgetauscht.

Siehe zum Beispiel den Deskriptor für hannes/duckdb_avro, der einige Wochen vor DuckDB v1.2.0 veröffentlicht wurde. Er hat sich in https://github.com/duckdb/community-extensions/pull/252/files geändert von:

repo:
  github: hannes/duckdb_avro
  ref: e5ed59b6ccf915c65e17eb6286b9a64f3ab09f59

zu:

repo:
  github: hannes/duckdb_avro
  ref: e5ed59b6ccf915c65e17eb6286b9a64f3ab09f59
  ref_next: c8941c92ec103f7825eb88207c04512f8a714b23

Hier ist ref mit DuckDB-Version v1.1.3 kompatibel und ref_next mit dem aktuellen main.

Beachten Sie, dass Kompatibilität mit dem aktuellen main keine Kompatibilität mit v1.2.0 garantieren kann, da Änderungen, die die Erweiterung betreffen, noch einfließen können. Es sollte aber ermöglichen, früh zu iterieren, bevor eine neue stabile DuckDB-Version erscheint.

Hilfe erhalten

Für Fragen zur Entwicklung von Erweiterungen gibt es einen eigenen Kanal auf dem DuckDB-Discord-Server. Der Discord-Server ist ein guter Ort, um Hilfe von anderen Erweiterungsentwicklern und dem DuckDB-Kernteam zu bekommen. Wenn Sie einen Fehler oder eine andere Art von Problem mit DuckDB, dem Extension Template oder der CI-Toolchain gefunden haben, öffnen Sie bitte einfach ein Issue im jeweiligen Repository und beschreiben Sie Ihr Problem. Wenn Sie unsicher sind, können Sie natürlich zuerst im Discord-Kanal nachfragen, ob es ein echtes Problem ist oder ob Sie es nur falsch halten.