Die aktuelle stabile Version des DuckDB-Kommandozeilen-Clients ist 1.5.5.
Installation
Die DuckDB-CLI (Command Line Interface) ist eine einzelne, abhängigkeitsfreie ausführbare Datei. Sie ist für Windows, Mac und Linux vorkompiliert, sowohl für die stabile Version als auch für Nightly-Builds aus GitHub Actions. Download-Links finden Sie auf der Installationsseite unter dem Reiter CLI.
Die DuckDB-CLI basiert auf der SQLite-Kommandozeilenshell, daher ist die CLI-spezifische Funktionalität ähnlich wie in der SQLite-Dokumentation beschrieben (obwohl die SQL-Syntax von DuckDB den Konventionen von PostgreSQL folgt, mit wenigen Ausnahmen).
DuckDB hat eine tldr-Seite, die die häufigsten Verwendungen des CLI-Clients zusammenfasst.
Wenn tldr installiert ist, können Sie sie mit tldr duckdb anzeigen.
Erste Schritte
Sobald die CLI-Datei heruntergeladen ist, entpacken Sie sie und speichern Sie sie in einem beliebigen Verzeichnis.
Wechseln Sie in einem Terminal in dieses Verzeichnis und geben Sie den Befehl duckdb ein, um die Datei auszuführen.
In einer PowerShell- oder POSIX-Shell-Umgebung verwenden Sie stattdessen den Befehl ./duckdb.
Verwendung
Die typische Verwendung des Befehls duckdb ist die folgende:
Ohne Argument ⟨FILENAME⟩{:.language-sql .highlight} öffnet die DuckDB-CLI eine temporäre In-Memory-Datenbank.
Sie sehen die Versionsnummer von DuckDB, Informationen zur Verbindung und eine Eingabeaufforderung, die mit einem D beginnt.
Terminal window
duckdb
DuckDB v1.5.5 (Variegata) d8cdaa33fd
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
D
Um eine persistente Datenbank zu öffnen oder zu erstellen, geben Sie einfach einen Pfad als Kommandozeilenargument an:
Terminal window
duckdb my_database.duckdb
SQL-Anweisungen in der CLI ausführen
Sobald die CLI geöffnet ist, geben Sie eine SQL-Anweisung gefolgt von einem Semikolon ein, drücken Sie Enter, und sie wird ausgeführt. Ergebnisse werden als Tabelle im Terminal angezeigt. Wird das Semikolon weggelassen, ermöglicht Enter die Eingabe mehrzeiliger SQL-Anweisungen.
SELECT'quack'AS my_column;
my_column
quack
Die CLI unterstützt die gesamte SQL-Syntax von DuckDB, einschließlich der Anweisungen SELECT, CREATE und ALTER.
Um die CLI zu beenden, drücken Sie Ctrl+D, falls Ihre Plattform das unterstützt. Andernfalls drücken Sie Ctrl+C oder verwenden Sie den Befehl .exit. Bei einer persistenten Datenbank führt DuckDB automatisch einen Checkpoint aus (speichert die letzten Änderungen auf die Festplatte) und schließt. Dabei wird die Datei .wal (das Write-Ahead-Log) entfernt und alle Daten in der Einzeldatei-Datenbank zusammengeführt.
Punktbefehle
Zusätzlich zur SQL-Syntax können spezielle Punktbefehle in den CLI-Client eingegeben werden. Um einen dieser Befehle zu verwenden, beginnen Sie die Zeile mit einem Punkt (.), unmittelbar gefolgt vom Namen des auszuführenden Befehls. Zusätzliche Argumente werden durch Leerzeichen getrennt nach dem Befehl eingegeben. Muss ein Argument ein Leerzeichen enthalten, können einfache oder doppelte Anführungszeichen das Parameter umschließen. Punktbefehle müssen in einer einzigen Zeile stehen, und vor dem Punkt darf kein Leerraum stehen. Am Zeilenende ist kein Semikolon erforderlich.
Häufig verwendete Einstellungen können in der Datei ~/.duckdbrc gespeichert werden, die beim Start des CLI-Clients geladen wird. Weitere Informationen zu diesen Optionen finden Sie im Abschnitt CLI konfigurieren.
Tipp Damit der DuckDB-CLI-Client die Datei ~/.duckdbrc nicht liest, starten Sie ihn so:
Terminal window
duckdb -init /dev/null
Nachfolgend fassen wir einige wichtige Punktbefehle zusammen. Alle verfügbaren Befehle finden Sie auf der Seite Punktbefehle oder mit dem Befehl .help.
Datenbankdateien öffnen
Zusätzlich zur Verbindung mit einer Datenbank beim Öffnen der CLI kann mit dem Befehl .open eine neue Datenbankverbindung hergestellt werden. Ohne weitere Parameter wird eine neue In-Memory-Datenbankverbindung erzeugt. Diese Datenbank wird nicht persistiert, wenn die CLI-Verbindung geschlossen wird.
.open
Der Befehl .open akzeptiert optional mehrere Optionen, der letzte Parameter kann aber einen Pfad zu einer persistenten Datenbank angeben (oder wo eine erstellt werden soll). Die besondere Zeichenkette :memory: kann ebenfalls verwendet werden, um eine temporäre In-Memory-Datenbank zu öffnen.
.open persistent.duckdb
Warnung .open schließt die aktuelle Datenbank.
Um die aktuelle Datenbank zu behalten und eine neue hinzuzufügen, verwenden Sie die Anweisung ATTACH.
Eine wichtige von .open akzeptierte Option ist das Flag --readonly. Damit sind keine Änderungen an der Datenbank möglich. Zum Öffnen im schreibgeschützten Modus muss die Datenbank bereits existieren. Eine neue In-Memory-Datenbank kann daher nicht schreibgeschützt geöffnet werden, weil In-Memory-Datenbanken erst bei der Verbindung erzeugt werden.
.open --readonly preexisting.duckdb
Die Option --sql erlaubt es, den Datenbankpfad über einen SQL-Ausdruck zu setzen:
.open --sql "getenv('MY_DB_PATH')"
Ausgabeformate
Der Punktbefehl.mode ändert das Erscheinungsbild der Tabellen in der Terminalausgabe.
Dazu gehören der Standardmodus duckbox, die Modi csv und json für die Weiterverarbeitung durch andere Werkzeuge, markdown und latex für Dokumente sowie der Modus insert zum Erzeugen von SQL-Anweisungen.
Ergebnisse in eine Datei schreiben
Standardmäßig sendet die DuckDB-CLI Ergebnisse an die Standardausgabe des Terminals. Das lässt sich mit den Befehlen .output oder .once ändern.
Einzelheiten finden Sie in der Dokumentation zum Ausgabe-Punktbefehl.
SQL aus einer Datei lesen
Die DuckDB-CLI kann SQL-Befehle und Punktbefehle statt aus dem Terminal aus einer externen Datei lesen, mit dem Befehl .read. So lassen sich mehrere Befehle nacheinander ausführen und Befehlsfolgen speichern und wiederverwenden.
Der Befehl .read erwartet nur ein Argument: den Pfad zur Datei mit dem auszuführenden SQL und/oder den Befehlen. Nach dem Ausführen der Befehle in der Datei kehrt die Steuerung zum Terminal zurück. Die Ausgabe dieser Ausführung unterliegt denselben Befehlen .output und .once, die bereits besprochen wurden. So kann die Ausgabe wieder im Terminal erscheinen, wie im ersten Beispiel, oder in eine andere Datei geschrieben werden, wie im zweiten Beispiel.
In diesem Beispiel liegt die Datei select_example.sql im selben Verzeichnis wie duckdb.exe und enthält die folgende SQL-Anweisung:
SELECT*
FROMgenerate_series(5);
Zum Ausführen aus der CLI wird der Befehl .read verwendet.
.read select_example.sql
Die folgende Ausgabe wird standardmäßig ins Terminal zurückgegeben. Die Formatierung der Tabelle lässt sich mit den Befehlen .output oder .once anpassen.
| generate_series |
|----------------:|
| 0 |
| 1 |
| 2 |
| 3 |
| 4 |
| 5 |
Mehrere Befehle, einschließlich SQL und Punktbefehlen, können auch in einem einzigen .read-Befehl ausgeführt werden. In diesem Beispiel liegt die Datei write_markdown_to_file.sql im selben Verzeichnis wie duckdb.exe und enthält die folgenden Befehle:
.mode markdown
.outputseries.md
SELECT*
FROMgenerate_series(5);
Zum Ausführen aus der CLI wird der Befehl .read wie zuvor verwendet.
.read write_markdown_to_file.sql
In diesem Fall wird keine Ausgabe ins Terminal zurückgegeben. Stattdessen wird die Datei series.md erzeugt (oder ersetzt, falls sie bereits existierte) mit den hier gezeigten, markdown-formatierten Ergebnissen:
| generate_series |
|----------------:|
| 0 |
| 1 |
| 2 |
| 3 |
| 4 |
| 5 |
CLI konfigurieren
Mehrere Punktbefehle können die CLI konfigurieren.
Beim Start liest und führt die CLI alle Befehle in der Datei ~/.duckdbrc aus, einschließlich Punktbefehlen und SQL-Anweisungen.
So können Sie den Konfigurationszustand der CLI speichern.
Sie können mit dem Flag -init auch auf eine andere Initialisierungsdatei verweisen.
Eine eigene Eingabeaufforderung setzen
Als Beispiel ändert eine Datei namens prompt.sql im selben Verzeichnis wie die DuckDB-CLI die DuckDB-Eingabeaufforderung in einen Entenkopf und führt eine SQL-Anweisung aus.
Beachten Sie, dass der Entenkopf aus Unicode-Zeichen besteht und nicht in allen Terminalumgebungen funktioniert (z. B. unter Windows, außer mit WSL und Windows Terminal).
Um diese Datei bei der Initialisierung aufzurufen, verwenden Sie diesen Befehl:
Terminal window
duckdb -init prompt.sql
Das gibt aus:
-- Loading resources from prompt.sql
v⟨version⟩ ⟨git_hash⟩
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
⚫◗
Nicht-interaktive Verwendung
Um eine Datei zu lesen/verarbeiten und sofort zu beenden, leiten Sie den Dateiinhalt in duckdb um:
Terminal window
duckdb < select_example.sql
Um einen Befehl mit direkt von der Kommandozeile übergebenem SQL-Text auszuführen, rufen Sie duckdb mit zwei Argumenten auf: dem Speicherort der Datenbank (oder :memory:) und einer Zeichenkette mit der auszuführenden SQL-Anweisung.
Terminal window
duckdb :memory: "SELECT 42 AS the_answer"
Erweiterungen laden
Zum Laden von Erweiterungen verwenden Sie die SQL-Befehle INSTALL und LOAD von DuckDB wie andere SQL-Anweisungen.
In einer Unix-Umgebung ist es oft nützlich, Daten zwischen mehreren Befehlen zu pipen.
DuckDB kann Daten von stdin lesen und nach stdout schreiben, indem in SQL-Befehlen die Dateipfade von stdin (/dev/stdin) und stdout (/dev/stdout) verwendet werden, da Pipes sich sehr ähnlich wie Dateihandles verhalten.
Dieser Befehl erzeugt eine Beispiel-CSV:
COPY (SELECT42AS woot UNION ALLSELECT43AS woot) TO'test.csv' (HEADER);
Lesen Sie zuerst eine Datei und pipen Sie sie an die ausführbare Datei der duckdb-CLI. Als Argumente an die DuckDB-CLI übergeben Sie den Speicherort der zu öffnenden Datenbank, hier eine In-Memory-Datenbank, und einen SQL-Befehl, der /dev/stdin als Dateipfad verwendet.
Terminal window
cat test.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"
woot
42
43
Zum Zurückschreiben nach stdout kann der Copy-Befehl mit dem Dateipfad /dev/stdout verwendet werden.
Terminal window
cat test.csv | \
duckdb -c "COPY (SELECT * FROM read_csv('/dev/stdin')) TO '/dev/stdout' WITH (FORMAT csv, HEADER)"
woot
42
43
Umgebungsvariablen lesen
Die Funktion getenv kann Umgebungsvariablen lesen.
Beispiele
Um den Pfad des Home-Verzeichnisses aus der Umgebungsvariable HOME zu ermitteln, verwenden Sie:
SELECT getenv('HOME') AS home;
home
/Users/user_name
Die Ausgabe der Funktion getenv kann verwendet werden, um Konfigurationsoptionen zu setzen. Um zum Beispiel die NULL-Reihenfolge anhand der Umgebungsvariable DEFAULT_NULL_ORDER zu setzen, verwenden Sie:
SET default_null_order = getenv('DEFAULT_NULL_ORDER');
Einschränkungen beim Lesen von Umgebungsvariablen
Die Funktion getenv kann nur ausgeführt werden, wenn die Option enable_external_access auf true gesetzt ist (die Standardeinstellung).
Sie ist nur im CLI-Client verfügbar und wird in anderen DuckDB-Clients nicht unterstützt.
Prepared Statements
Die DuckDB-CLI unterstützt das Ausführen von Prepared Statements zusätzlich zu regulären SELECT-Anweisungen.
Um ein Prepared Statement im CLI-Client zu erzeugen und auszuführen, verwenden Sie die Klausel PREPARE und die Anweisung EXECUTE.
Geschätzte verbleibende Abfragezeit (ETA)
Die CLI von DuckDB liefert inzwischen intelligente Schätzungen der verbleibenden Zeit für laufende Abfragen und zeigt nach Abschluss die gesamte Ausführungszeit an.
Beim Ausführen von Abfragen in der DuckDB-CLI zeigt der Fortschrittsbalken eine geschätzte Restzeit bis zum Abschluss. Diese Funktion verwendet fortgeschrittene statistische Modellierung (Kalman-Filterung), um genauere Vorhersagen zu liefern als eine einfache lineare Extrapolation.
So funktioniert es
DuckDB berechnet die geschätzte Zeit bis zum Abschluss wie folgt:
Fortschrittsüberwachung: Die interne Progress-API von DuckDB meldet den geschätzten Fertigstellungsprozentsatz der laufenden Abfrage
Statistische Filterung: Ein Kalman-Filter glättet verrauschte Fortschrittsmessungen und berücksichtigt Schwankungen bei der Ausführung
Kontinuierliche Verfeinerung: Das System aktualisiert die vorhergesagte Abschlusszeit fortlaufend, sobald neue Fortschrittsdaten vorliegen, und verbessert so die Genauigkeit während der Ausführung
Der Kalman-Filter passt sich an wechselnde Ausführungsbedingungen an, etwa Speicherdruck, E/A-Engpässe oder Netzverzögerungen. Durch diesen adaptiven Ansatz nimmt die geschätzte Abschlusszeit nicht immer linear ab – die Schätzungen können steigen, wenn die Abfrageausführung weniger vorhersehbar wird.
Faktoren, die die Genauigkeit der ETA beeinflussen
Schätzungen der Abschlusszeit können unter diesen Bedingungen weniger zuverlässig sein:
Einschränkungen der Systemressourcen:
Speicherdruck mit Auslagerung auf die Festplatte
Hohe CPU-Last durch konkurrierende Prozesse
Festplatten-E/A-Engpässe
Eigenschaften der Abfrageausführung:
Unterschiedliche Ausführungsphasen (anfängliche Vorbereitung gegenüber Hauptverarbeitung)
Netzwerkabhängige Operationen mit ungleichmäßiger Latenz
Abfragen mit unvorhersehbarer Verzweigungslogik
Operationen auf entfernten Datenquellen
Aufrufe externer Funktionen
Stark schiefe Datenverteilungen
Dies ist eine inoffizielle Website und nicht mit DuckDB verbunden. Offizielle Seite:duckdb.org.duckdb.ubitools.com · Übersetzt und erstellt mit Astro und daisyUI
