YDB Dialect for SQLAlchemy
This repository contains YQL dialect for SqlAlchemy 2.0.
Documentation: https://ydb-platform.github.io/ydb-sqlalchemy
Note: Dialect also works with SqlAlchemy 1.4, but it is not fully tested.
Installation
Via PyPI
To install ydb-sqlalchemy from PyPI:
$ pip install ydb-sqlalchemy
Installation from source code
To work with current ydb-sqlalchemy version clone this repo and run from source root:
$ pip install -U .
Getting started
Connect to local YDB using SqlAlchemy:
import sqlalchemy as sa
engine = sa.create_engine("yql+ydb://localhost:2136/local")
with engine.connect() as conn:
rs = conn.execute(sa.text("SELECT 1 AS value"))
print(rs.fetchone())
Authentication
To specify credentials, you should pass credentials object to connect_args argument of create_engine method.
Static Credentials
To use static credentials you should specify username and password as follows:
engine = sa.create_engine(
"yql+ydb://localhost:2136/local",
connect_args = {
"credentials": {
"username": "...",
"password": "..."
}
}
)
Token Credentials
To use access token credentials you should specify token as follows:
engine = sa.create_engine(
"yql+ydb://localhost:2136/local",
connect_args = {
"credentials": {
"token": "..."
}
}
)
Service Account Credentials
To use service account credentials you should specify service_account_json as follows:
engine = sa.create_engine(
"yql+ydb://localhost:2136/local",
connect_args = {
"credentials": {
"service_account_json": {
"id": "...",
"service_account_id": "...",
"created_at": "...",
"key_algorithm": "...",
"public_key": "...",
"private_key": "..."
}
}
}
)
Credentials from YDB SDK
To use any credentials that comes with ydb package, just pass credentials object as follows:
import ydb.iam
engine = sa.create_engine(
"yql+ydb://localhost:2136/local",
connect_args = {
"credentials": ydb.iam.MetadataUrlCredentials()
}
)
Migrations
To setup alembic to work with YDB please check this example.
Development
Run Tests:
Run the command from the root directory of the repository to start YDB in a local docker container.
$ docker-compose up
To run all tests execute the command from the root directory of the repository:
$ tox -e test-all
Run specific test:
$ tox -e test -- test/test_core.py
Check code style:
$ tox -e style
Reformat code:
$ tox -e isort
$ tox -e black-format
Run example (needs running local YDB):
$ python -m pip install virtualenv
$ virtualenv venv
$ source venv/bin/activate
$ pip install -r requirements.txt
$ python examples/example.py
Additional Notes
Pandas
It is possible to use YDB SA engine with pandas fuctions to_sql() and read_sql. However, there are some limitations:
-
to_sqlmethod can not be used with column tables, since it is impossible to specifyNOT NULLcolumns with currentto_sqlarguments. YDB requires column tables to haveNOT NULLattribute onPKcolumns. -
to_sqlis not fully optimized to load huge datasets. It is recommended to usemethod="multi"and avoid setting a very largechunksize. -
read_sqlis not fully optimized to load huge datasets and could lead to significant memory consumptions.
Metadata
Release files for ydb-sqlalchemy 0.1.24
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ydb_sqlalchemy-0.1.24.tar.gz | 52.0 kB | Without provenance | Details for ydb_sqlalchemy-0.1.24.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ydb_sqlalchemy-0.1.24-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details for ydb_sqlalchemy-0.1.24-py2.py3-none-any.whl |
Total release size: 110.4 kB
Release files / ydb_sqlalchemy-0.1.24.tar.gz
| Download URL | ydb_sqlalchemy-0.1.24.tar.gz |
|---|---|
| Size | 52.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8b458b864e8138facb1dfb9ae41aaf9c831e6dba29912515749e5880f1417954
|
|
BLAKE2b-256 checksum How to use checksums |
f952435593e15a1905022ed844e181877c59d2eafd41c4861ddaa9568ad44653
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.14
|
Release files / ydb_sqlalchemy-0.1.24-py2.py3-none-any.whl
| Download URL | ydb_sqlalchemy-0.1.24-py2.py3-none-any.whl |
|---|---|
| Size | 58.5 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
c9e6721b299844271b9a896752952cc4febfd5c8bac59ce1d70bc1fb47e0f5b2
|
|
BLAKE2b-256 checksum How to use checksums |
288db6e50a34d17c98092f2bd5df7646e288de46def078ef2c13b41c1e6331d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/5.0.0 CPython/3.12.14
|
Security for ydb-sqlalchemy 0.1.24
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.