# YDB Dialect for SQLAlchemy
---
[](https://github.com/ydb-platform/ydb-sqlalchemy/blob/main/LICENSE)
[](https://badge.fury.io/py/ydb-sqlalchemy)
[](https://ydb-platform.github.io/ydb-sqlalchemy/api/index.html)
[](https://github.com/ydb-platform/ydb-sqlalchemy/actions/workflows/tests.yml)
[](https://github.com/ydb-platform/ydb-sqlalchemy/actions/workflows/style.yml)
This repository contains YQL dialect for SqlAlchemy 2.0.
---
**Documentation**: <a href="https://ydb-platform.github.io/ydb-sqlalchemy" target="_blank">https://ydb-platform.github.io/ydb-sqlalchemy</a>
---
**Note**: Dialect also works with SqlAlchemy 1.4, but it is not fully tested.
## Installation
### Via PyPI
To install ydb-sqlalchemy from PyPI:
```bash
$ pip install ydb-sqlalchemy
```
### Installation from source code
To work with current ydb-sqlalchemy version clone this repo and run from source root:
```bash
$ pip install -U .
```
## Getting started
Connect to local YDB using SqlAlchemy:
```python3
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:
```python3
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:
```python3
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:
```python3
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:
```python3
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](https://github.com/ydb-platform/ydb-sqlalchemy/tree/main/examples/alembic).
## Development
### Run Tests:
Run the command from the root directory of the repository to start YDB in a local docker container.
```bash
$ docker-compose up
```
To run all tests execute the command from the root directory of the repository:
```bash
$ tox -e test-all
```
Run specific test:
```bash
$ tox -e test -- test/test_core.py
```
Check code style:
```bash
$ tox -e style
```
Reformat code:
```bash
$ tox -e isort
$ tox -e black-format
```
Run example (needs running local YDB):
```bash
$ 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()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_sql.html) and [read_sql](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_sql.html). However, there are some limitations:
* `to_sql` method can not be used with column tables, since it is impossible to specify `NOT NULL` columns with current `to_sql` arguments. YDB requires column tables to have `NOT NULL` attribute on `PK` columns.
* `to_sql` is not fully optimized to load huge datasets. It is recommended to use `method="multi"` and avoid setting a very large `chunksize`.
* `read_sql` is not fully optimized to load huge datasets and could lead to significant memory consumptions.
Raw data
{
"_id": null,
"home_page": "http://github.com/ydb-platform/ydb-sqlalchemy",
"name": "ydb-sqlalchemy",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "SQLAlchemy YDB YQL",
"author": "Yandex LLC",
"author_email": "ydb@yandex-team.ru",
"download_url": "https://files.pythonhosted.org/packages/16/69/5c225794963b7a78678b6cb6f34619919aba127f7b535b0ace4a592451f7/ydb_sqlalchemy-0.1.11.tar.gz",
"platform": null,
"description": "# YDB Dialect for SQLAlchemy\n---\n[](https://github.com/ydb-platform/ydb-sqlalchemy/blob/main/LICENSE)\n[](https://badge.fury.io/py/ydb-sqlalchemy)\n[](https://ydb-platform.github.io/ydb-sqlalchemy/api/index.html)\n[](https://github.com/ydb-platform/ydb-sqlalchemy/actions/workflows/tests.yml)\n[](https://github.com/ydb-platform/ydb-sqlalchemy/actions/workflows/style.yml)\n\nThis repository contains YQL dialect for SqlAlchemy 2.0.\n\n---\n\n**Documentation**: <a href=\"https://ydb-platform.github.io/ydb-sqlalchemy\" target=\"_blank\">https://ydb-platform.github.io/ydb-sqlalchemy</a>\n\n---\n\n**Note**: Dialect also works with SqlAlchemy 1.4, but it is not fully tested.\n\n\n## Installation\n\n### Via PyPI\nTo install ydb-sqlalchemy from PyPI:\n\n```bash\n$ pip install ydb-sqlalchemy\n```\n\n### Installation from source code\nTo work with current ydb-sqlalchemy version clone this repo and run from source root:\n\n```bash\n$ pip install -U .\n```\n\n## Getting started\n\nConnect to local YDB using SqlAlchemy:\n\n```python3\nimport sqlalchemy as sa\n\n\nengine = sa.create_engine(\"yql+ydb://localhost:2136/local\")\n\nwith engine.connect() as conn:\n rs = conn.execute(sa.text(\"SELECT 1 AS value\"))\n print(rs.fetchone())\n\n```\n\n## Authentication\n\nTo specify credentials, you should pass `credentials` object to `connect_args` argument of `create_engine` method.\n\n### Static Credentials\n\nTo use static credentials you should specify `username` and `password` as follows:\n\n```python3\nengine = sa.create_engine(\n \"yql+ydb://localhost:2136/local\",\n connect_args = {\n \"credentials\": {\n \"username\": \"...\",\n \"password\": \"...\"\n }\n }\n)\n```\n\n### Token Credentials\n\nTo use access token credentials you should specify `token` as follows:\n\n```python3\nengine = sa.create_engine(\n \"yql+ydb://localhost:2136/local\",\n connect_args = {\n \"credentials\": {\n \"token\": \"...\"\n }\n }\n)\n```\n\n### Service Account Credentials\n\nTo use service account credentials you should specify `service_account_json` as follows:\n\n```python3\nengine = sa.create_engine(\n \"yql+ydb://localhost:2136/local\",\n connect_args = {\n \"credentials\": {\n \"service_account_json\": {\n \"id\": \"...\",\n \"service_account_id\": \"...\",\n \"created_at\": \"...\",\n \"key_algorithm\": \"...\",\n \"public_key\": \"...\",\n \"private_key\": \"...\"\n }\n }\n }\n)\n```\n\n### Credentials from YDB SDK\n\nTo use any credentials that comes with `ydb` package, just pass credentials object as follows:\n\n```python3\nimport ydb.iam\n\nengine = sa.create_engine(\n \"yql+ydb://localhost:2136/local\",\n connect_args = {\n \"credentials\": ydb.iam.MetadataUrlCredentials()\n }\n)\n\n```\n\n\n## Migrations\n\nTo setup `alembic` to work with `YDB` please check [this example](https://github.com/ydb-platform/ydb-sqlalchemy/tree/main/examples/alembic).\n\n## Development\n\n### Run Tests:\n\nRun the command from the root directory of the repository to start YDB in a local docker container.\n```bash\n$ docker-compose up\n```\n\nTo run all tests execute the command from the root directory of the repository:\n```bash\n$ tox -e test-all\n```\n\nRun specific test:\n```bash\n$ tox -e test -- test/test_core.py\n```\n\nCheck code style:\n```bash\n$ tox -e style\n```\n\nReformat code:\n```bash\n$ tox -e isort\n$ tox -e black-format\n```\n\nRun example (needs running local YDB):\n```bash\n$ python -m pip install virtualenv\n$ virtualenv venv\n$ source venv/bin/activate\n$ pip install -r requirements.txt\n$ python examples/example.py\n```\n\n## Additional Notes\n\n### Pandas\nIt is possible to use YDB SA engine with `pandas` fuctions [to_sql()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.to_sql.html) and [read_sql](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_sql.html). However, there are some limitations:\n\n* `to_sql` method can not be used with column tables, since it is impossible to specify `NOT NULL` columns with current `to_sql` arguments. YDB requires column tables to have `NOT NULL` attribute on `PK` columns.\n\n* `to_sql` is not fully optimized to load huge datasets. It is recommended to use `method=\"multi\"` and avoid setting a very large `chunksize`.\n\n* `read_sql` is not fully optimized to load huge datasets and could lead to significant memory consumptions.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "YDB Dialect for SQLAlchemy",
"version": "0.1.11",
"project_urls": {
"Homepage": "http://github.com/ydb-platform/ydb-sqlalchemy"
},
"split_keywords": [
"sqlalchemy",
"ydb",
"yql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e07a5292b37dfbde33f837036893bbea5d0686109812d4a0338099a8480b5ac0",
"md5": "3961ab1ac6cc29e4b1350f413cce629b",
"sha256": "5861ddfab324ee5b0d6eacf9d663108b6a66508650284ccccb42a52335e6abac"
},
"downloads": -1,
"filename": "ydb_sqlalchemy-0.1.11-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "3961ab1ac6cc29e4b1350f413cce629b",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 39622,
"upload_time": "2025-10-24T09:21:50",
"upload_time_iso_8601": "2025-10-24T09:21:50.228192Z",
"url": "https://files.pythonhosted.org/packages/e0/7a/5292b37dfbde33f837036893bbea5d0686109812d4a0338099a8480b5ac0/ydb_sqlalchemy-0.1.11-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16695c225794963b7a78678b6cb6f34619919aba127f7b535b0ace4a592451f7",
"md5": "6af1d50a445f1ed1697969088c4e0888",
"sha256": "2ba241a15eef0143f23580b659ab9195a7d1d21641090b4ee78fdcad330cb1c3"
},
"downloads": -1,
"filename": "ydb_sqlalchemy-0.1.11.tar.gz",
"has_sig": false,
"md5_digest": "6af1d50a445f1ed1697969088c4e0888",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 35790,
"upload_time": "2025-10-24T09:21:51",
"upload_time_iso_8601": "2025-10-24T09:21:51.641597Z",
"url": "https://files.pythonhosted.org/packages/16/69/5c225794963b7a78678b6cb6f34619919aba127f7b535b0ace4a592451f7/ydb_sqlalchemy-0.1.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-24 09:21:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ydb-platform",
"github_project": "ydb-sqlalchemy",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "sqlalchemy",
"specs": [
[
"<",
"3.0.0"
],
[
">=",
"1.4.0"
]
]
},
{
"name": "ydb",
"specs": [
[
">=",
"3.21.6"
]
]
},
{
"name": "ydb-dbapi",
"specs": [
[
">=",
"0.1.10"
]
]
}
],
"tox": true,
"lcname": "ydb-sqlalchemy"
}
JSON
