CLI API

Установка

CLI DuckDB (Командная строка интерфейс) — это единственный, независимый от зависимостей исполняемый файл. Он предварительно скомпилирован для Windows, Mac и Linux как для стабильной версии, так и для ночных сборок, созданных GitHub Actions. См. страницу страницы установки на вкладке CLI для ссылок для скачивания.

CLI DuckDB основан на командной оболочке SQLite, поэтому функциональность CLI-клиента аналогична описанной в документации SQLite (хотя синтаксис SQL DuckDB следует соглашениям PostgreSQL с некоторыми исключениями).

DuckDB имеет страницу tldr, которая обобщает наиболее распространенные использования CLI-клиента. Если у вас установлен tldr, вы можете отобразить его, выполнив tldr duckdb.

Начало работы

После скачивания исполняемого файла CLI разархивируйте его и сохраните в любой директории. Перейдите в эту директорию в терминале и введите команду duckdb для запуска исполняемого файла. Если вы находитесь в среде PowerShell или POSIX, используйте команду ./duckdb вместо нее.

Использование

Типичное использование команды duckdb следующее:

duckdb [OPTIONS] [FILENAME]

Параметры

Часть [OPTIONS] кодирует аргументы для CLI-клиента. К распространенным параметрам относятся:

• -csv: устанавливает режим вывода в CSV
• -json: устанавливает режим вывода в JSON
• -readonly: открывает базу данных в режиме только для чтения (см. конкурентность в DuckDB)

Полный список параметров см. на странице аргументов командной строки.

Временная база данных против постоянной базы данных

Если не предоставлен параметр [FILENAME], CLI DuckDB откроет временную временную базу данных. Вы увидите номер версии DuckDB, информацию о подключении и приглашение, начинающееся с D.

duckdb

v1.1.3 19864453f7
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
D

Чтобы открыть или создать постоянную базу данных, просто включите путь в качестве аргумента командной строки:

duckdb my_database.duckdb

Выполнение SQL-запросов в CLI

После открытия CLI введите SQL-запрос, за которым следует точка с запятой, затем нажмите Enter, и он будет выполнен. Результаты будут отображаться в таблице в терминале. Если точка с запятой опущена, нажатие Enter позволит вводить многострочные SQL-запросы.

SELECT 'quack' AS my_column;

CLI поддерживает весь богатый синтаксис SQL DuckDB, включая SELECT, CREATE, и ALTER команды.

Функции редактора

CLI поддерживает автозаполнение, а также имеет сложные функции редактора и подсветку синтаксиса на определенных платформах.

Выход из CLI

Для выхода из CLI нажмите Ctrl+D, если ваша платформа это поддерживает. В противном случае нажмите Ctrl+C или используйте команду .exit. Если используется постоянная база данных, DuckDB автоматически сделает контрольную точку (сохранит последние изменения на диске) и закроется. Это удалит файл .wal (журнал предварительной записи) и объединит все ваши данные в базу данных одного файла.

Команды с точкой

В дополнение к синтаксису SQL в CLI-клиент можно ввести специальные команды с точкой. Чтобы использовать одну из этих команд, начните строку с точки (.) сразу после имени команды, которую вы хотите выполнить. Дополнительные аргументы для команды вводятся через пробел после команды. Если аргумент должен содержать пробел, можно использовать одинарные или двойные кавычки для обертывания этого параметра. Команды с точкой должны вводиться в одну строку, и пробелы не должны встречаться перед точкой. Точка с запятой в конце строки не требуется.

Часто используемые конфигурации можно хранить в файле ~/.duckdbrc, который будет загружен при запуске CLI-клиента. См. раздел Настройка CLI ниже для получения дополнительной информации об этих параметрах.

Ниже мы обобщаем несколько важных команд с точкой. Чтобы увидеть все доступные команды, см. страницу страница команд с точкой или используйте команду .help.

Открытие файлов базы данных

Помимо подключения к базе данных при открытии CLI, новое подключение к базе данных можно создать, используя команду .open. Если дополнительных параметров не указано, создается новое подключение к временной базе данных. Эта база данных не будет сохранена при закрытии подключения CLI.

.open

Команда .open необязательно принимает несколько параметров, но последний параметр можно использовать для указания пути к постоянной базе данных (или где она должна быть создана). Специальную строку :memory: также можно использовать для открытия временной временной базы данных.

.open persistent.duckdb

Предупреждение .open закрывает текущую базу данных. Чтобы сохранить текущую базу данных, добавив новую базу данных, используйте ATTACH команду.

Один важный параметр, принимаемый командой .open, — флаг --readonly. Это запрещает любые изменения в базе данных. Чтобы открыть в режиме только для чтения, база данных должна уже существовать. Это также означает, что новую временную базу данных нельзя открыть в режиме только для чтения, так как временные базы данных создаются при подключении.

.open --readonly preexisting.duckdb

Форматы вывода

Команда .mode команда с точкой может использоваться для изменения внешнего вида таблиц, возвращаемых в выводе терминала. Они включают в себя режим по умолчанию duckbox, csv и json режимы для импорта другими инструментами, markdown и latex для документов и insert режим для генерации SQL-запросов.

Запись результатов в файл

По умолчанию CLI DuckDB отправляет результаты в стандартный вывод терминала. Однако это можно изменить, используя команды .output или .once. Для получения подробной информации см. документацию по команде с точкой output.

Чтение SQL из файла

DuckDB CLI может считывать SQL-команды и команды с точкой из внешнего файла вместо терминала, используя команду .read. Это позволяет запускать ряд команд последовательно и позволяет сохранять и повторно использовать последовательности команд.

Команда .read требует только одного аргумента: путь к файлу, содержащему SQL- и/или команды для выполнения. После выполнения команд в файле управление возвращается в терминал. Вывод от выполнения этого файла регулируется теми же командами .output и .once, что и ранее обсуждались. Это позволяет отобразить вывод обратно в терминал, как в первом примере ниже, или в другой файл, как во втором примере.

В этом примере файл select_example.sql находится в той же папке, что и duckdb.exe, и содержит следующий SQL-запрос:

SELECT *
FROM generate_series(5);

Для его выполнения из CLI используется команда .read.

.read select_example.sql

Вывод ниже по умолчанию возвращается в терминал. Форматирование таблицы можно настроить с помощью команд .output или .once.

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

Несколько команд, включая SQL и команды с точкой, также могут быть выполнены в одной команде .read. В этом примере файл write_markdown_to_file.sql находится в той же папке, что и duckdb.exe, и содержит следующие команды:

.mode markdown
.output series.md
SELECT *
FROM generate_series(5);

Для его выполнения из CLI, как и прежде, используется команда .read.

.read write_markdown_to_file.sql

В этом случае вывод не возвращается в терминал. Вместо этого создается (или заменяется, если уже существовал) файл series.md с отформатированными результатами, показанными здесь:

| generate_series |
|----------------:|
| 0               |
| 1               |
| 2               |
| 3               |
| 4               |
| 5               |

Настройка CLI

Для настройки CLI можно использовать несколько команд с точкой. При запуске CLI читает и выполняет все команды в файле ~/.duckdbrc, включая команды с точкой и SQL-запросы. Это позволяет сохранить состояние конфигурации CLI. Вы также можете указать другой файл инициализации, используя -init.

Установка пользовательского приглашения

Например, файл в той же папке, что и CLI DuckDB, с именем prompt.sql изменит приглашение DuckDB на изображение головы утки и выполнит SQL-запрос. Обратите внимание, что изображение головы утки создано с помощью Unicode-символов и не работает во всех средах терминала (например, в Windows, если не запущен WSL и не используется Windows Terminal).

.prompt '⚫◗ '

Чтобы вызвать этот файл при инициализации, используйте следующую команду:

duckdb -init prompt.sql

Это выведет:

-- 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.
⚫◗

Неинтерактивное использование

Чтобы прочитать/обработать файл и немедленно выйти, перенаправьте содержимое файла в duckdb:

duckdb < select_example.sql

Для выполнения команды с текстом SQL, переданным непосредственно из командной строки, вызовите duckdb с двумя аргументами: местоположение базы данных (или :memory:) и строку с SQL-запросом для выполнения.

duckdb :memory: "SELECT 42 AS the_answer"

Загрузка расширений

Для загрузки расширений используйте SQL-команды DuckDB INSTALL и LOAD так же, как и другие SQL-запросы.

INSTALL fts;
LOAD fts;

Подробности см. в документации по расширениям.

Чтение из stdin и запись в stdout

В Unix-среде полезно передавать данные между несколькими командами через конвейеры. DuckDB может читать данные из stdin и записывать в stdout, используя местоположение файла stdin (/dev/stdin) и stdout (/dev/stdout) в SQL-командах, так как конвейеры работают очень похоже на файловые дескрипторы.

Эта команда создаст пример CSV:

COPY (SELECT 42 AS woot UNION ALL SELECT 43 AS woot) TO 'test.csv' (HEADER);

Сначала прочтите файл и передайте его в исполняемый файл duckdb CLI. В качестве аргументов для DuckDB CLI укажите расположение базы данных для открытия, в данном случае — базу данных в памяти, и SQL-команду, которая использует /dev/stdin как местоположение файла.

cat test.csv | duckdb -c "SELECT * FROM read_csv('/dev/stdin')"

Для записи обратно в stdout можно использовать команду copy с местоположением файла /dev/stdout.

cat test.csv | \
    duckdb -c "COPY (SELECT * FROM read_csv('/dev/stdin')) TO '/dev/stdout' WITH (FORMAT 'csv', HEADER)"

woot
42
43

Чтение переменных окружения

Функция getenv может читать переменные окружения.

Примеры

Чтобы получить путь к домашней директории из переменной окружения HOME, используйте:

SELECT getenv('HOME') AS home;

Результат работы функции getenv может использоваться для установки параметров конфигурации. Например, чтобы установить порядок NULL на основе переменной окружения DEFAULT_NULL_ORDER, используйте:

SET default_null_order = getenv('DEFAULT_NULL_ORDER');

Ограничения чтения переменных окружения

Функция getenv может быть запущена только в том случае, если enable_external_access установлено в значение true (значение по умолчанию). Она доступна только в клиенте CLI и не поддерживается в других клиентах DuckDB.

Предзаготовленные запросы

DuckDB CLI поддерживает выполнение предзаготовленных запросов помимо обычных SELECT запросов. Для создания и выполнения предзаготовленного запроса в клиенте CLI используйте предложение PREPARE и оператор EXECUTE.