Перейти к основному содержимому

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

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, RisingWaveasyncpg
MySQL, StarRocksasyncmy
Apache Doris, OceanBaseaiomysql
ClickHouseasynch
Trinoaiotrino
Microsoft SQL Server / Azure SQLaioodbc
Oracleoracledb (thin, async)
Apache Pinotasync HTTP (pinotdb)
AWS Athenapyathena (REST)
AWS DynamoDBaioboto3
Elasticsearch / OpenDistroasync Elasticsearch-клиент
Azure Data Explorer (Kusto — SQL и KQL)async HTTP
Databenddatabend
Firebirdfirebirdsql
Fireboltfirebolt
YDBydb
примечание

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

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

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

База данных
PyPI пакетConnection String (пример)
AWS Athenapip install pyathena[pandas]awsathena+rest://{access_key_id}:{access_key}@athena.{region}.amazonaws.com/{schema}?...
AWS DynamoDBpip install pydynamodbdynamodb://{access_key_id}:{secret_access_key}@dynamodb.{region}.amazonaws.com?...
AWS Redshiftpip install sqlalchemy-redshiftredshift+psycopg2://<userName>:<DBPassword>@<End Point>:5439/<Database Name>
Apache Dorispip install pydorisdoris://<User>:<Password>@<Host>:<Port>/<Catalog>.<Database>
Apache Drillpip install sqlalchemy-drilldrill+sadrill://<username>:<password>@<host>:<port>/<storage_plugin>
Apache Druidpip install pydruiddruid://<User>:<password>@<Host>:<Port>/druid/v2/sql
Apache Hivepip install pyhivehive://hive@{hostname}:{port}/{database}
Apache Impalapip install impylaimpala://{hostname}:{port}/{database}
Apache Kylinpip install kylinpykylin://<username>:<password>@<hostname>:<port>/<project>
Apache Pinotpip install pinotdbpinot://BROKER:5436/query?server=http://CONTROLLER:5983/
Apache Solrpip install sqlalchemy-solrsolr://{username}:{password}@{hostname}:{port}/{server_path}/{collection}
Apache Spark SQLpip install pyhivehive://hive@{hostname}:{port}/{database}
Ascend.iopip install impylaascend://{username}:{password}@{hostname}:{port}/{database}
Azure MS SQLpip install pymssqlmssql+pymssql://...
ClickHousepip install clickhouse-connectclickhousedb://{username}:{password}@{hostname}:{port}/{database}
CockroachDBpip install cockroachdbcockroachdb://root@{hostname}:{port}/{database}?sslmode=disable
Couchbasepip install couchbase-sqlalchemycouchbase://{username}:{password}@{hostname}:{port}
CrateDBpip install sqlalchemy-cratedbcrate://{username}:{password}@{hostname}:{port}
Denodopip install denodo-sqlalchemydenodo://{username}:{password}@{hostname}:{port}/{database}
Dremiopip install sqlalchemy_dremiodremio+flight://{username}:{password}@{host}:32010
Elasticsearchpip install elasticsearch-dbapielasticsearch+http://{user}:{password}@{host}:9200/
Exasolpip install sqlalchemy-exasolexa+pyodbc://{username}:{password}@{hostname}:{port}/my_schema
Google BigQuerypip install sqlalchemy-bigquerybigquery://{project_id}
Google Sheetspip install shillelagh[gsheetsapi]gsheets://
Fireboltpip install firebolt-sqlalchemyfirebolt://{client_id}:{client_secret}@{database}/{engine_name}
Hologrespip install psycopg2postgresql+psycopg2://...
IBM Db2pip install ibm_db_sadb2+ibm_db://
IBM Netezza Performance Serverpip install nzalchemynetezza+nzpy://<UserName>:<DBPassword>@<Database Host>/<Database Name>
MySQLpip install mysqlclientmysql://<UserName>:<DBPassword>@<Database Host>/<Database Name>
OceanBasepip install oceanbase_pyoceanbase://<UserName>:<DBPassword>@<Database Host>/<Database Name>
Oraclepip install cx_Oracleoracle://<username>:<password>@<hostname>:<port>
Parseablepip install sqlalchemy-parseableparseable://<UserName>:<DBPassword>@<Database Host>/<Stream Name>
PostgreSQLpip install psycopg2postgresql://<UserName>:<DBPassword>@<Database Host>/<Database Name>
Prestopip install pyhivepresto://{username}:{password}@{hostname}:{port}/{database}
SAP Hanapip install hdbcli sqlalchemy-hanahana://{username}:{password}@{host}:{port}
SingleStorepip install sqlalchemy-singlestoredbsinglestoredb://{username}:{password}@{host}:{port}/{database}
StarRockspip install starrocksstarrocks://<User>:<Password>@<Host>:<Port>/<Catalog>.<Database>
Snowflakepip install snowflake-sqlalchemysnowflake://{user}:{password}@{account}.{region}/{database}?role={role}&warehouse={...}
SQLiteдополнительная библиотека не требуетсяsqlite://path/to/file.db?check_same_thread=false
SQL Serverpip install pymssqlmssql+pymssql://<Username>:<Password>@<Host>:<Port>/<Database Name>
TDenginepip install taospy pip install taos-ws-pytaosws://<user>:<password>@<host>:<port>
Teradatapip install teradatasqlalchemyteradatasql://{user}:{password}@{host}
TimescaleDBpip install psycopg2postgresql://<UserName>:<DBPassword>@<Database Host>:<Port>/<Database Name>
Trinopip install trinotrino://{username}:{password}@{hostname}:{port}/{catalog}
Verticapip install sqlalchemy-vertica-pythonvertica+vertica_python://<UserName>:<DBPassword>@<Database Host>/<Database Name>
YDBpip install ydb-sqlalchemyydb://{host}:{port}/{database_name}
YugabyteDBpip install psycopg2postgresql://<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:// и т. п. См. англоязычную версию для рецептов.