Подключение к базам данных

Liteset не идёт с предустановленными драйверами БД. Главный шаг подключения Liteset к БД — установить нужные драйверы в окружение.

примечание

Вам понадобятся пакеты для БД метаданных и для всех источников данных, к которым вы будете подключаться через Liteset. Про настройку БД метаданных — см. Docker Compose, Kubernetes.

к сведению

Полный список БД-специфичных инструкций (около 40 движков с примерами connection-string'ов и нюансами) — в англоязычной версии страницы. Эта русская версия содержит обзорные таблицы и общие инструкции.

Эта страница ссылается на драйверы для часто используемых движков.

Установка драйверов БД

Liteset требует установленного Python DB-API драйвера и SQLAlchemy-диалекта для каждого движка, к которому вы подключаетесь.

Подробнее об установке новых драйверов в Liteset — см. Установка драйверов в Docker-образах.

Как Liteset подключается: async- и sync-драйверы

Liteset работает с базами данных через async-движок SQLAlchemy 2.0. В отличие от Apache Superset, который синхронен от и до, у Liteset два пути подключения, и он выбирает нужный автоматически по типу движка БД:

• Нативные async-драйверы. Для движков с настоящим asyncio DB-API Liteset поставляет отдельный async engine spec (superset/db/engine_specs/), который выполняет запросы не блокируя event loop. Пока один запрос ждёт ответа БД, тот же воркер обслуживает другие — именно отсюда прирост пропускной способности и хвостовой латентности в бенчмарках.
• Sync-фолбэк. Любая другая поддерживаемая SQLAlchemy база продолжает работать через SyncFallbackEngineSpec, который выполняет стандартный синхронный DB-API (psycopg2, pymysql, snowflake-sqlalchemy, …) через greenlet-мост SQLAlchemy run_sync. Это сохраняет весь каталог БД Superset без потери функциональности — ценой того, что такой запрос занимает свою корутину до завершения и не отдаёт event loop, как нативный async-драйвер.

Вы устанавливаете те же пакеты драйверов и используете те же SQLAlchemy-URI, что и в Apache Superset (см. таблицу ниже). Строки подключения переписывать не нужно: Liteset определяет engine spec по backend'у из URI и, если нативный async-спек и его драйвер доступны, использует async-драйвер под капотом.

Движки с нативным async engine spec:

Движок(и) БД	Нативный async-драйвер
PostgreSQL — и Postgres-wire движки TimescaleDB, Hologres, YugabyteDB, AWS Redshift, CockroachDB, CrateDB, Denodo, RisingWave	asyncpg
MySQL, StarRocks	asyncmy
Apache Doris, OceanBase	aiomysql
ClickHouse	asynch
Trino	aiotrino
Microsoft SQL Server / Azure SQL	aioodbc
Oracle	oracledb (thin, async)
Apache Pinot	async HTTP (pinotdb)
AWS Athena	pyathena (REST)
AWS DynamoDB	aioboto3
Elasticsearch / OpenDistro	async Elasticsearch-клиент
Azure Data Explorer (Kusto — SQL и KQL)	async HTTP
Databend	databend
Firebird	firebirdsql
Firebolt	firebolt
YDB	ydb

примечание

Async-драйверы, входящие в образ Liteset — это asyncpg, aiosqlite (SQLite) и aiotrino; они покрывают БД метаданных и наиболее нагруженные аналитические движки. PostgreSQL, MySQL, ClickHouse и Trino — четыре движка, проверенные под нагрузочными тестами. Для любого другого движка — async или sync — установите соответствующий пакет драйвера ровно так же, как в Apache Superset, по таблице из следующего раздела.

Поддерживаемые БД и зависимости

Рекомендуемые пакеты ниже. Версии, совместимые с Liteset — см. pyproject.toml.

База данных	PyPI пакет	Connection String (пример)
AWS Athena	pip install pyathena[pandas]	awsathena+rest://{access_key_id}:{access_key}@athena.{region}.amazonaws.com/{schema}?...
AWS DynamoDB	pip install pydynamodb	dynamodb://{access_key_id}:{secret_access_key}@dynamodb.{region}.amazonaws.com?...
AWS Redshift	pip install sqlalchemy-redshift	redshift+psycopg2://<userName>:<DBPassword>@<End Point>:5439/<Database Name>
Apache Doris	pip install pydoris	doris://<User>:<Password>@<Host>:<Port>/<Catalog>.<Database>
Apache Drill	pip install sqlalchemy-drill	drill+sadrill://<username>:<password>@<host>:<port>/<storage_plugin>
Apache Druid	pip install pydruid	druid://<User>:<password>@<Host>:<Port>/druid/v2/sql
Apache Hive	pip install pyhive	hive://hive@{hostname}:{port}/{database}
Apache Impala	pip install impyla	impala://{hostname}:{port}/{database}
Apache Kylin	pip install kylinpy	kylin://<username>:<password>@<hostname>:<port>/<project>
Apache Pinot	pip install pinotdb	pinot://BROKER:5436/query?server=http://CONTROLLER:5983/
Apache Solr	pip install sqlalchemy-solr	solr://{username}:{password}@{hostname}:{port}/{server_path}/{collection}
Apache Spark SQL	pip install pyhive	hive://hive@{hostname}:{port}/{database}
Ascend.io	pip install impyla	ascend://{username}:{password}@{hostname}:{port}/{database}
Azure MS SQL	pip install pymssql	mssql+pymssql://...
ClickHouse	pip install clickhouse-connect	clickhousedb://{username}:{password}@{hostname}:{port}/{database}
CockroachDB	pip install cockroachdb	cockroachdb://root@{hostname}:{port}/{database}?sslmode=disable
Couchbase	pip install couchbase-sqlalchemy	couchbase://{username}:{password}@{hostname}:{port}
CrateDB	pip install sqlalchemy-cratedb	crate://{username}:{password}@{hostname}:{port}
Denodo	pip install denodo-sqlalchemy	denodo://{username}:{password}@{hostname}:{port}/{database}
Dremio	pip install sqlalchemy_dremio	dremio+flight://{username}:{password}@{host}:32010
Elasticsearch	pip install elasticsearch-dbapi	elasticsearch+http://{user}:{password}@{host}:9200/
Exasol	pip install sqlalchemy-exasol	exa+pyodbc://{username}:{password}@{hostname}:{port}/my_schema
Google BigQuery	pip install sqlalchemy-bigquery	bigquery://{project_id}
Google Sheets	pip install shillelagh[gsheetsapi]	gsheets://
Firebolt	pip install firebolt-sqlalchemy	firebolt://{client_id}:{client_secret}@{database}/{engine_name}
Hologres	pip install psycopg2	postgresql+psycopg2://...
IBM Db2	pip install ibm_db_sa	db2+ibm_db://
IBM Netezza Performance Server	pip install nzalchemy	netezza+nzpy://<UserName>:<DBPassword>@<Database Host>/<Database Name>
MySQL	pip install mysqlclient	mysql://<UserName>:<DBPassword>@<Database Host>/<Database Name>
OceanBase	pip install oceanbase_py	oceanbase://<UserName>:<DBPassword>@<Database Host>/<Database Name>
Oracle	pip install cx_Oracle	oracle://<username>:<password>@<hostname>:<port>
Parseable	pip install sqlalchemy-parseable	parseable://<UserName>:<DBPassword>@<Database Host>/<Stream Name>
PostgreSQL	pip install psycopg2	postgresql://<UserName>:<DBPassword>@<Database Host>/<Database Name>
Presto	pip install pyhive	presto://{username}:{password}@{hostname}:{port}/{database}
SAP Hana	pip install hdbcli sqlalchemy-hana	hana://{username}:{password}@{host}:{port}
SingleStore	pip install sqlalchemy-singlestoredb	singlestoredb://{username}:{password}@{host}:{port}/{database}
StarRocks	pip install starrocks	starrocks://<User>:<Password>@<Host>:<Port>/<Catalog>.<Database>
Snowflake	pip install snowflake-sqlalchemy	snowflake://{user}:{password}@{account}.{region}/{database}?role={role}&warehouse={...}
SQLite	дополнительная библиотека не требуется	sqlite://path/to/file.db?check_same_thread=false
SQL Server	pip install pymssql	mssql+pymssql://<Username>:<Password>@<Host>:<Port>/<Database Name>
TDengine	pip install taospy pip install taos-ws-py	taosws://<user>:<password>@<host>:<port>
Teradata	pip install teradatasqlalchemy	teradatasql://{user}:{password}@{host}
TimescaleDB	pip install psycopg2	postgresql://<UserName>:<DBPassword>@<Database Host>:<Port>/<Database Name>
Trino	pip install trino	trino://{username}:{password}@{hostname}:{port}/{catalog}
Vertica	pip install sqlalchemy-vertica-python	vertica+vertica_python://<UserName>:<DBPassword>@<Database Host>/<Database Name>
YDB	pip install ydb-sqlalchemy	ydb://{host}:{port}/{database_name}
YugabyteDB	pip install psycopg2	postgresql://<UserName>:<DBPassword>@<Database Host>/<Database Name>

---

Поддерживаются и другие БД — главный критерий — наличие функционального SQLAlchemy-диалекта и Python-драйвера. Поиск по ключевому слову sqlalchemy + (имя бд) обычно приводит к нужному.

Если вашей БД нет в списке, но у неё есть SQL-интерфейс — заведите issue, будем работать над поддержкой.

Чтобы написать собственный database connector для Liteset — см. этот туториал.

Установка драйверов в Docker-образах

Liteset требует Python-драйвер для каждого типа БД. Пример с MySQL — процесс одинаков для всех:

1. Определите нужный драйвер

В таблице выше найдите PyPI-пакет (для MySQL — mysqlclient).

2. Расширьте Docker-образ

Создайте requirements-local.txt рядом с docker-compose-файлом:

touch ./docker/requirements-local.txt

Добавьте в него драйвер:

mysqlclient

3. Перезапустите Liteset

docker compose down
docker compose up

Драйверы установятся при следующей сборке образа.

4. Подключите БД через UI

См. Подключение через UI ниже.

Инструкции для конкретных БД

Для каждой из ~40 поддерживаемых БД в Liteset есть индивидуальные особенности (генерация service-credentials в BigQuery, токены для Snowflake, sslmode для Postgres / Redshift, kerberos для Hive и т. д.). Полные пошаговые инструкции для каждой — см. англоязычную версию. Базовая «формула» одинакова:

1. Установить драйвер из таблицы.
2. Получить credentials у владельца БД.
3. Сформировать connection string по примеру выше.
4. В Liteset UI: Settings → Database Connections → + Database, ввести URI, проверить Test Connection.

Подключение через UI

Краткий путь:

1. Settings → Database Connections.
2. + Database в правом верхнем углу.
3. Выберите тип БД из списка.
4. В простом режиме введите host, port, database, username, password — Liteset сам соберёт URI.
5. В режиме SQLAlchemy URI введите готовую строку (см. примеры в таблице выше).
6. Test Connection — Liteset проверит подключение.
7. Connect — сохранит подключение.

После подключения база появится в Sources → Databases, и вы можете регистрировать таблицы как датасеты.

Дополнительные настройки БД

В диалоге edit-БД на вкладке Advanced доступны параметры:

• SQL Lab settings — Expose in SQL Lab, Allow CREATE TABLE AS, Allow CREATE VIEW AS, Allow DML, Allow this database to be explored, Allow file uploads.
• Performance — Chart cache timeout, Schemas allowed for CSV upload, Asynchronous query execution.
• Security — Enable secure extra (encrypted JSON для credentials), Root certificate (для self-signed TLS), Impersonate logged in user, Allow dataset/file uploads.
• Other — Metadata cache timeout, Version, Engine Parameters.

Подробное описание каждого поля — в англоязычной версии.

Misc

Запросы между БД

Liteset поддерживает datasource-аналог cross-database queries через shillelagh — драйвер, который умеет читать данные из других БД, REST API, CSV и Google Sheets через виртуальные таблицы. Используйте connection string gsheets://, csv:// и т. п. См. англоязычную версию для рецептов.