Установка окружения: CLI, Python, наборы данных для лабораторных

Дальше курс наполнен практикой. Почти каждый урок содержит блок «Попробуй сам» с командами, которые нужно выполнить самостоятельно. Чтобы они работали, нужно один раз правильно настроить окружение: установить CLI, установить Python-клиент, проверить версии и подготовить тестовые данные.

Этот урок — ровно про это. Он короткий и инструментальный. После него у вас будет всё, чтобы выполнять лабораторные на протяжении всего курса. Потратить время на аккуратную настройку сейчас выгодно: правильно собранное один раз окружение избавит вас от мелких затыков в каждом последующем уроке, и вы сможете сосредоточиться на содержании, а не на технических неполадках.

Версия, на которую мы ориентируемся — DuckDB 1.5.2 (последняя стабильная) либо линия 1.4.x «Andium» (LTS). Любая из них подойдёт. Если у вас уже установлена более старая версия — обновитесь, потому что курс активно использует возможности 1.4 и 1.5.

Стоит коротко пояснить разницу между «последней стабильной» и «LTS». Последняя стабильная версия (на момент курса — 1.5.2) — это самый свежий выпуск со всеми новыми возможностями. LTS (Long-Term Support, долгосрочная поддержка) — это выпуск, который получает поддержку и исправления в течение продлённого срока; в DuckDB роль LTS играет линия 1.4 «Andium». Для прохождения курса подходит любая из двух: 1.5 даст вам самые новые возможности, 1.4 LTS — более «консервативный» вариант с длительной поддержкой. Для учебных целей различие непринципиально — берите то, что удобнее установить. Важно лишь не оказаться на версии старее 1.4: курс опирается на возможности, появившиеся в 1.4 и 1.5, и на более ранней версии часть примеров не сработает.

Два инструмента: CLI и Python-клиент

DuckDB можно использовать из множества языков, но в этом курсе мы опираемся на два инструмента. Такой выбор не случаен: CLI и Python-клиент покрывают два разных режима работы — быстрые интерактивные проверки и программные пайплайны, — и вместе они закрывают практически все учебные сценарии курса.

CLI — интерактивная командная строка. Запускаете duckdb, попадаете в приглашение, пишете SQL. Идеально для быстрых проверок, разведки данных, экспериментов с диалектом. Версия 1.5 принесла обновлённый «friendly CLI»: цветовые схемы, динамическое приглашение, постраничный вывод.

Python-клиент — библиотека duckdb. Это главный программный интерфейс DuckDB и основной клиент для инженера данных: через него DuckDB встраивается в скрипты, ноутбуки и пайплайны, обменивается данными с pandas, Polars, Arrow.

Важная деталь: за обоими инструментами стоит один и тот же движок. CLI не «облегчённая версия» — это тот же DuckDB с тем же оптимизатором и тем же исполнителем. Разница только в интерфейсе. Поэтому замер производительности в CLI и в Python даст одинаковый результат.

Установка Python-клиента

Python-клиент устанавливается стандартным pip — это обычный пакет Python, без особых системных требований:

pip install duckdb

Проверьте, что установилось, и какая версия:

python3 -c "import duckdb; print(duckdb.__version__)"

Ожидаемый вывод (число может отличаться, но major-minor должны быть 1.5 или 1.4):

1.5.2

Полезно установить заодно pandas, Polars и PyArrow — они понадобятся в модуле про Python-стек, и пригодятся для лабораторных раньше:

pip install pandas polars pyarrow

Установка CLI

С версии 1.5 CLI распространяется как отдельный пакет — его удобно поставить тем же pip:

pip install duckdb-cli

Альтернатива — скачать готовый бинарник с https://duckdb.org/docs/installation/. Это один файл без зависимостей: положили в PATH — и всё. На macOS работает и brew install duckdb.

Какой способ выбрать — зависит от вашей ситуации. Если вы и так работаете в Python-окружении, pip install duckdb-cli удобнее всего: CLI встанет рядом с библиотекой одной командой. Если Python-окружение вам не нужно, а нужен только интерактивный CLI, проще скачать готовый бинарник — это буквально один файл, который не требует ничего, кроме как положить его в PATH. На macOS установка через brew — привычный для пользователей этой системы путь. Все три способа дают абсолютно одинаковый CLI: разница только в механизме доставки одного и того же файла. Это, кстати, наглядное проявление свойства «single binary», о котором шла речь в первом уроке курса, — движок настолько самодостаточен, что его установка сводится к получению одного файла любым удобным способом.

DuckDB кроссплатформенный — он работает на Linux, macOS и Windows, и на разных архитектурах процессоров. Для прохождения курса подойдёт любая из этих систем; команды в уроках даны в форме, работающей на Linux и macOS, а пользователям Windows иногда нужно лишь слегка адаптировать синтаксис командной строки (например, активацию виртуального окружения). Сам движок и SQL ведут себя одинаково на всех платформах.

Проверка установки:

duckdb --version

Вывод:

v1.5.2 8e52ec4395

Запустите CLI без аргументов — откроется in-memory сессия:

duckdb

Вы увидите приглашение. Выполните пробный запрос и завершите сессию командой .quit:

v1.5.2 8e52ec4395
Enter ".help" for usage hints.
Connected to a transient in-memory database.
Use ".open FILENAME" to reopen on a persistent database.
D SELECT 'окружение готово' AS status;
┌──────────────────┐
│      status      │
│     varchar      │
├──────────────────┤
│ окружение готово │
└──────────────────┘
D .quit

Приглашение D — это и есть friendly CLI 1.5. Команды, начинающиеся с точки (.help, .quit, .open, .tables) — это dot-команды, мета-команды CLI; их мы разберём подробно в модуле 02.

Persistent-файл против in-memory

Запущенный без аргументов CLI работает с транзиентной in-memory базой: данные живут только в оперативной памяти и исчезают при выходе. Это удобно для экспериментов.

Чтобы данные сохранялись, передайте имя файла:

duckdb my_lab.duckdb

Теперь всё, что вы создаёте, пишется в файл my_lab.duckdb на диске и переживает перезапуск. Тот же выбор есть и в Python:

import duckdb

# in-memory: исчезнет после завершения процесса
con_mem = duckdb.connect()

# persistent: сохранится в файл
con_disk = duckdb.connect("my_lab.duckdb")

Для лабораторных курса используйте in-memory там, где нужен быстрый эксперимент, и persistent-файл там, где урок просит сохранить данные между шагами. Каждый урок укажет, что именно нужно.

Тестовые наборы данных

Для лабораторных пригодятся данные. У DuckDB есть встроенный генератор TPC-H — это стандартный аналитический бенчмарк, который можно использовать как набор реалистичных таблиц.

В CLI или Python выполните:

INSTALL tpch;
LOAD tpch;
CALL dbgen(sf = 0.1);

sf — scale factor, множитель объёма. sf = 0.1 создаёт небольшой набор (примерно 100 МБ, около 600 тысяч строк в самой крупной таблице lineitem) — этого достаточно для большинства уроков и быстро генерируется. Для уроков про larger-than-memory вам предложат sf побольше.

Проверьте, что таблицы появились:

SHOW TABLES;

Вывод — восемь таблиц схемы TPC-H:

┌──────────┐
│   name   │
│ varchar  │
├──────────┤
│ customer │
│ lineitem │
│ nation   │
│ orders   │
│ part     │
│ partsupp │
│ region   │
│ supplier │
└──────────┘

Быстрый проверочный запрос — сколько строк в lineitem:

SELECT count(*) AS rows FROM lineitem;

┌────────┐
│  rows  │
│ int64  │
├────────┤
│ 600572 │
└────────┘

Если эти команды отработали без ошибок — окружение полностью готово. Помимо TPC-H, отдельные уроки будут использовать публичные Parquet/CSV-файлы; их адреса будут даны прямо в задании.

Стоит пояснить, почему именно TPC-H выбран как набор данных для курса. TPC-H — это стандартный отраслевой бенчмарк для аналитических СУБД: он моделирует данные оптовой торговли и состоит из восьми связанных таблиц с реалистичными отношениями между ними — заказы, позиции заказов, клиенты, поставщики, товары. Для обучения это удобно сразу по нескольким причинам. Во-первых, схема реалистична: на ней естественно отрабатывать соединения, агрегации, группировки — то есть настоящую аналитику, а не игрушечные примеры. Во-вторых, объём данных регулируется одним параметром sf, поэтому один и тот же набор можно взять маленьким для быстрых уроков и большим для уроков про larger-than-memory. В-третьих, TPC-H общеизвестен — встретив его в документации DuckDB или в чужих статьях о производительности, вы будете понимать, о чём речь. Генератор dbgen встроен в расширение tpch, поэтому данные создаются локально и не требуют ничего скачивать.

Проверка, что окружение действительно работает

Установить пакеты — половина дела. Важно убедиться, что окружение не просто «вроде стоит», а реально работает так, как ожидается. Сделаем это сознательно, а не на авось.

Первое — версии. Курс опирается на возможности версий 1.4 и 1.5, поэтому критично, чтобы и Python-клиент, и CLI были именно этих версий. Проверьте оба и сверьте major-minor числа:

python3 -c "import duckdb; print('python-client:', duckdb.__version__)"
duckdb --version

Если одно из чисел показывает что-то старее 1.4 — обновитесь. Особенно легко упустить рассинхрон, когда Python-клиент и CLI ставились в разное время: они могут оказаться разных версий. Для курса держите их согласованными.

Второе — что движок реально исполняет SQL. Минимальная проверка — выполнить запрос и увидеть осмысленный результат:

import duckdb
print(duckdb.sql("SELECT 'works' AS status, version() AS v").fetchone())
# ('works', 'v1.5.2')

Функция version() возвращает версию движка изнутри самого SQL — это удобный способ подтвердить, что движок не только импортировался, но и отвечает на запросы.

Третье — что persistent-режим действительно пишет на диск. Это проверяется только перезапуском процесса: создать таблицу в файле, закрыть, открыть файл заново, убедиться, что таблица на месте. Именно эту проверку делает задание ниже, и пропускать её не стоит — она единственная по-настоящему доказывает, что данные сохраняются.

Типичные проблемы при настройке

Чтобы не застрять на старте, разберём несколько частых проблем и их причины.

Версии Python-клиента и CLI не совпадают. Самое частое. Причина в том, что pip install duckdb и pip install duckdb-cli — два отдельных пакета, и обновив один, легко забыть про другой. Решение — обновлять оба вместе и сверять duckdb.__version__ с duckdb --version.

Установка «уехала» из-за работы вне виртуального окружения. Если ставить пакеты в системный Python, версии легко смешиваются с тем, что нужно другим проектам, и потом непонятно, какая версия фактически активна. Решение — одно виртуальное окружение на весь курс, как описано выше.

CALL dbgen отработал, но после перезапуска таблиц нет. Причина — CLI был запущен в in-memory режиме, и данные исчезли с процессом. Это не ошибка, а ожидаемое поведение in-memory базы. Решение — запускать CLI с persistent-файлом для данных, которые должны сохраняться.

INSTALL tpch не проходит. INSTALL для core-расширения скачивает его, поэтому шагу нужен доступ в интернет. Если установка не идёт, первое, что стоит проверить, — сетевое соединение.

Эти четыре ситуации покрывают почти все затыки при настройке. Объединяет их одно: понимая причину (два пакета; системный Python; in-memory режим; нужен интернет), вы решаете проблему сразу, а не гадаете.

Попробуй сам

Соберите окружение целиком и зафиксируйте, что всё работает. Выполните по шагам:

1. Создайте виртуальное окружение и активируйте его.
2. Установите duckdb, duckdb-cli, pandas, polars, pyarrow.
3. Проверьте версии: python3 -c "import duckdb; print(duckdb.__version__)" и duckdb --version. Убедитесь, что обе показывают 1.5.x или 1.4.x.
4. Создайте persistent-файл tpch.duckdb, сгенерируйте в нём данные TPC-H с sf = 0.1.
5. Закройте CLI, откройте файл заново (duckdb tpch.duckdb) и выполните SHOW TABLES — убедитесь, что восемь таблиц на месте после перезапуска.

Последний шаг — главный: он доказывает, что persistent-режим действительно сохраняет данные на диск. Если таблицы пережили перезапуск процесса, окружение настроено правильно, и вы готовы к остальному курсу.