Versionierung von Erweiterungen

Versionierung von Erweiterungen

Die meiste Software hat irgendeine Versionsnummer. Versionsnummern dienen einigen wichtigen Zielen:

• Eine Binärdatei an einen bestimmten Stand des Quellcodes binden
• Den erwarteten Funktionsumfang bestimmen
• Den Stand der APIs bestimmen
• Fehlermeldungen effizient verarbeiten (z. B. wurde Bug #1337 in Version v3.4.5 eingeführt)
• Die chronologische Reihenfolge von Releases bestimmen (z. B. ist Version v1.2.3 älter als v1.2.4)
• Einen Hinweis auf die erwartete Stabilität geben (z. B. ist v0.0.1 wahrscheinlich nicht sehr stabil, während v13.11.0 es vermutlich ist)

Genau wie DuckDB selbst haben DuckDB-Erweiterungen eine eigene Versionsnummer. Um einheitliche Semantik dieser Versionsnummern über die verschiedenen Erweiterungen hinweg zu gewährleisten, verwenden die Core-Erweiterungen von DuckDB ein Versionierungsschema, das vorschreibt, wie Erweiterungen versioniert werden sollen. Das Versionierungsschema für Core-Erweiterungen besteht aus 3 verschiedenen Stabilitätsstufen: unstable, pre-release und stable. Gehen wir die 3 Stufen durch und beschreiben ihr Format:

Unstable-Erweiterungen

Unstable-Erweiterungen sind Erweiterungen, die keine Garantien zu ihrer aktuellen Stabilität oder zu dem Ziel, stabil zu werden, geben können (oder wollen). Unstable-Erweiterungen sind mit dem kurzen Git-Hash der Erweiterung gekennzeichnet.

Zum Zeitpunkt der Erstellung dieses Texts ist die Version der Erweiterung vss beispielsweise eine Unstable-Erweiterung der Version 690bfc5.

Was ist von einer Erweiterung mit einer Versionsnummer im Format unstable zu erwarten?

• Den Stand des Quellcodes der Erweiterung finden Sie, indem Sie den Hash im Erweiterungs-Repository nachschlagen
• Funktionalität kann sich mit jedem Release ändern oder vollständig entfernt werden
• Die API dieser Erweiterung kann sich mit jedem Release ändern
• Diese Erweiterung folgt möglicherweise keinem strukturierten Release-Zyklus; neue (breaking) Versionen können jederzeit veröffentlicht werden

Pre-Release-Erweiterungen

Pre-Release-Erweiterungen sind der nächste Schritt über Unstable-Erweiterungen hinaus. Sie sind mit einer Version im Format SemVer gekennzeichnet, genauer gesagt im Format v0.y.z. In der semantischen Versionierung haben Versionen, die mit v0 beginnen, eine besondere Bedeutung: Sie zeigen an, dass die strengere Semantik regulärer Versionen (>v1.0.0) noch nicht gilt. Das bedeutet im Wesentlichen, dass eine Erweiterung auf dem Weg zu einer stabilen Erweiterung ist, aber noch nicht ganz dort.

Zum Zeitpunkt der Erstellung dieses Texts ist die Version der Erweiterung delta beispielsweise eine Pre-Release-Erweiterung der Version v0.1.0.

Was ist von einer Erweiterung mit einer Versionsnummer im Format pre-release zu erwarten?

• Die Erweiterung wird aus dem Quellcode kompiliert, der dem Tag entspricht.
• Die Semantik der semantischen Versionierung gilt. Details finden Sie in der Spezifikation zur semantischen Versionierung.
• Die Erweiterung folgt einem Release-Zyklus, in dem neue Funktionen in Nightly-Builds getestet werden, bevor sie zu einem Release zusammengefasst und ins Repository core übertragen werden.
• Release Notes, die beschreiben, was in jedem Release hinzugekommen ist, sollten verfügbar sein, damit sich die Unterschiede zwischen den Versionen leicht nachvollziehen lassen.

Stabile Erweiterungen

Stabile Erweiterungen sind die letzte Stufe der Erweiterungsstabilität. Das wird durch ein stabiles SemVer im Format vx.y.z mit x>0 gekennzeichnet.

Zum Zeitpunkt der Erstellung dieses Texts ist die Version der Erweiterung parquet beispielsweise eine stabile Erweiterung der Version v1.0.0.

Was ist von einer Erweiterung mit einer Versionsnummer im Format stable zu erwarten? Im Wesentlichen dasselbe wie bei Pre-Release-Erweiterungen, aber jetzt gilt die strengere SemVer-Semantik: Die API der Erweiterung sollte nun stabil sein und sich nur dann in nicht abwärtskompatibler Weise ändern, wenn die Major-Version erhöht wird. Details finden Sie in der SemVer-Spezifikation

Release-Zyklus von Pre-Release- und stabilen Core-Erweiterungen

Im Allgemeinen hängt der Release-Zyklus von Erweiterungen von ihrer Stabilitätsstufe ab. unstable-Erweiterungen sind oft mit dem Release-Zyklus von DuckDB synchron, können aber auch stillschweigend zwischen DuckDB-Releases aktualisiert werden. pre-release- und stable- Erweiterungen folgen einem eigenen Release-Zyklus. Dieser kann mit DuckDB-Releases zusammenfallen, muss es aber nicht. Mehr zum Release-Zyklus einer bestimmten Erweiterung finden Sie in der Dokumentation oder auf der GitHub-Seite der jeweiligen Erweiterung. In der Regel dokumentieren pre-release- und stable-Erweiterungen ihre Releases als GitHub-Releases; ein Beispiel sehen Sie in der delta-Erweiterung.

Schließlich gibt es eine kleine Ausnahme: Alle In-Tree-Erweiterungen folgen einfach dem Release-Zyklus von DuckDB.

Nightly-Builds

Genau wie DuckDB selbst haben die Core-Erweiterungen von DuckDB Nightly- oder Dev-Builds, mit denen sich Funktionen ausprobieren lassen, bevor sie offiziell veröffentlicht werden. Das kann nützlich sein, wenn Ihr Workflow von einer neuen Funktion abhängt oder wenn Sie prüfen müssen, ob Ihr Stack mit der kommenden Version kompatibel ist.

Nightly-Builds für Erweiterungen sind etwas komplizierter, weil Erweiterungsbinärdateien von DuckDB derzeit fest an eine einzelne DuckDB-Version gebunden sind. Wegen dieser engen Verbindung besteht das Risiko einer kombinatorischen Explosion. Daher sind nicht alle Kombinationen aus Nightly-Erweiterungs-Build und Nightly-DuckDB-Build verfügbar.

Es gibt grundsätzlich 2 Wege, Nightly-Builds zu nutzen: mit einem Nightly-Build von DuckDB und mit einem stabilen DuckDB-Build. Gehen wir die Unterschiede durch:

Mit stabilem DuckDB

In den meisten Fällen interessieren sich Nutzer für einen Nightly-Build einer bestimmten Erweiterung, wollen aber nicht unbedingt auf den Nightly-Build von DuckDB selbst umsteigen. So lässt sich eine bestimmte brandneue Funktion nutzen und gleichzeitig die Exposition gegenüber unstabilem Code begrenzen.

Dazu veröffentlichen Core-Erweiterungen regelmäßig Builds im Repository core_nightly. Schauen wir uns ein Beispiel an:

Zuerst installieren wir einen stabilen DuckDB-Build.

Dann können wir eine Nightly-Erweiterung so installieren und laden:

INSTALL aws FROM core_nightly;
LOAD aws;

In diesem Beispiel verwenden wir den neuesten Nightly-Build der aws-Erweiterung mit der neuesten stabilen Version von DuckDB.

Mit Nightly-DuckDB

Wenn die DuckDB-CI eine Nightly-Binärdatei von DuckDB selbst erzeugt, werden die Binärdateien mit einem Satz Erweiterungen ausgeliefert, die auf eine bestimmte Version gepinnt sind. Diese Erweiterungsversion wird für diesen bestimmten DuckDB-Build getestet, ist aber möglicherweise nicht der neueste Dev-Build. Schauen wir uns ein Beispiel an:

Zuerst installieren wir einen Nightly-DuckDB-Build. Dann können wir die Erweiterung aws wie erwartet installieren und laden:

INSTALL aws;
LOAD aws;

Erweiterungen aktualisieren

DuckDB hat eine eigene Anweisung, die automatisch alle Erweiterungen auf ihre neueste Version aktualisiert. Die Ausgabe gibt dem Nutzer Auskunft darüber, welche Erweiterungen von/auf welche Version aktualisiert wurden. Zum Beispiel:

UPDATE EXTENSIONS;

extension_name	repository	update_result	previous_version	current_version
httpfs	core	NO_UPDATE_AVAILABLE	70fd6a8a24	70fd6a8a24
delta	core	UPDATED	d9e5cc1	04c61e4
azure	core	NO_UPDATE_AVAILABLE	49b63dc	49b63dc
aws	core_nightly	NO_UPDATE_AVAILABLE	42c78d3	42c78d3

Beachten Sie, dass DuckDB in dem Quell-Repository jeder Erweiterung nach Updates sucht. Wenn eine Erweiterung also aus core_nightly installiert wurde, wird sie mit dem neuesten Nightly-Build aktualisiert.

Die Update-Anweisung kann auch mit einer Liste bestimmter zu aktualisierender Erweiterungen aufgerufen werden:

UPDATE EXTENSIONS (httpfs, azure);

extension_name	repository	update_result	previous_version	current_version
httpfs	core	NO_UPDATE_AVAILABLE	70fd6a8a24	70fd6a8a24
azure	core	NO_UPDATE_AVAILABLE	49b63dc	49b63dc

Ziel-DuckDB-Version

Derzeit sind Erweiterungen beim Kompilieren an eine bestimmte DuckDB-Version gebunden. Das bedeutet zum Beispiel, dass eine für Version 0.10.3 kompilierte Erweiterungsbinärdatei nicht für Version 1.0.0 funktioniert. In den meisten Fällen führt das zu keinen Problemen und ist vollständig transparent; DuckDB stellt automatisch sicher, dass es die richtige Binärdatei für seine Version installiert. Für Erweiterungsentwickler bedeutet das, dass sie bei jeder neuen DuckDB-Version neue Binärdateien erzeugen müssen. DuckDB stellt jedoch eine Erweiterungsvorlage bereit, die das vergleichsweise einfach macht.

In-Tree vs. Out-of-Tree

Ursprünglich lagen DuckDB-Erweiterungen ausschließlich im Haupt-Repository von DuckDB, github.com/duckdb/duckdb. Diese Erweiterungen heißen In-Tree. Später kam das Konzept der Out-of-Tree-Erweiterungen hinzu: Erweiterungen wurden in ein eigenes Repository ausgelagert, das wir Out-of-Tree nennen.

Aus Nutzersicht gibt es in der Regel keine merklichen Unterschiede, aber es gibt einige kleinere Unterschiede bei der Versionierung:

• In-Tree-Erweiterungen verwenden die Version von DuckDB, statt eine eigene Version zu haben
• In-Tree-Erweiterungen haben keine eigenen Release Notes; ihre Änderungen spiegeln sich in den regulären DuckDB-Release-Notes wider
• Core-Out-of-Tree-Erweiterungen liegen in der Regel in Repositories namens github.com/duckdb/duckdb-⟨extension_name⟩{:.language-sql .highlight}, der Name kann aber abweichen. Details finden Sie in der vollständigen Liste der Core-Erweiterungen.