https://github.com/firebolt-db/firebolt-sqlalchemy
The Firebolt dialect for SQLAlchemy.
https://github.com/firebolt-db/firebolt-sqlalchemy
firebolt sqlalchemy
Last synced: about 1 month ago
JSON representation
The Firebolt dialect for SQLAlchemy.
- Host: GitHub
- URL: https://github.com/firebolt-db/firebolt-sqlalchemy
- Owner: firebolt-db
- License: apache-2.0
- Created: 2021-08-24T14:13:03.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2025-04-24T09:00:23.000Z (about 1 month ago)
- Last Synced: 2025-04-29T21:18:36.438Z (about 1 month ago)
- Topics: firebolt, sqlalchemy
- Language: Python
- Homepage:
- Size: 1.27 MB
- Stars: 7
- Watchers: 4
- Forks: 7
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# firebolt-sqlalchemy
[](https://github.com/firebolt-db/firebolt-sqlalchemy/actions/workflows/unit-tests.yml)
[](https://github.com/firebolt-db/firebolt-sqlalchemy/actions/workflows/code-check.yml)
[](https://github.com/firebolt-db/firebolt-sqlalchemy/actions/workflows/security-scan.yml)
[](https://github.com/firebolt-db/firebolt-sqlalchemy/actions/workflows/python-integration-tests.yml)
The [Firebolt](https://www.firebolt.io/) dialect for [SQLAlchemy](https://www.sqlalchemy.org/). `firebolt-sqlalchemy` uses [Firebolt's Python SDK](https://github.com/firebolt-db/firebolt-python-sdk) which implements [PEP 249](https://www.python.org/dev/peps/pep-0249/).
* [SQLAlchemy Dialects](https://docs.sqlalchemy.org/en/20/dialects/index.html#external-dialects)
* [PyPI Package](https://pypi.org/project/firebolt-sqlalchemy/)
## Installation
Requires Python >=3.7.
```bash
pip install firebolt-sqlalchemy
```
## Connecting
Connection strings use the following structure:
```
firebolt://{client_id}:{client_secret}@{database}[/{engine_name}]?account_name={name}
```
`engine_name` is optional.
`account_name` is required.
Examples:
```
firebolt://aaa-bbb-ccc-222:$ecret@sample_database?account_name=my_account
firebolt://aaa-bbb-ccc-222:$ecret@sample_database/sample_engine?account_name=my_account
```
To override the API URL (e.g. for dev testing):
```bash
export FIREBOLT_BASE_URL=
```
If your secret contains % or / characters they need to be sanitised as per https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls
```python
my_secret = "0920%/2"
import urllib.parse
new_secret = urllib.parse.quote_plus(my_secret)
```
## Quick Start
```python
import urllib.parse
from sqlalchemy import create_engine
secret = urllib.parse.quote_plus("your_secret_here")
engine = create_engine("firebolt://aaa-bbb-ccc-222:" + secret + "@sample_database/sample_engine?account_name=my_account")
connection = engine.connect()
connection.execute("CREATE FACT TABLE example(dummy int) PRIMARY INDEX dummy")
connection.execute("INSERT INTO example(dummy) VALUES (11)")
result = connection.execute("SELECT * FROM example")
for item in result.fetchall():
print(item)
```
### [AsyncIO](https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html) extension
```python
import urllib.parse
from sqlalchemy import text
from sqlalchemy.ext.asyncio import create_async_engine
secret = urllib.parse.quote_plus("your_secret_here")
engine = create_async_engine("asyncio+firebolt://aaa-bbb-ccc-222:" + secret + "@sample_database/sample_engine?account_name=my_account")
async with engine.connect() as conn:
await conn.execute(
text(f"INSERT INTO example(dummy) VALUES (11)")
)
result = await conn.execute(
text(f"SELECT * FROM example")
)
print(result.fetchall())
await engine.dispose()
```
## Limitations
1. Transactions are not supported since Firebolt database does not support them at this time.
1. Parametrised calls to execute and executemany are not implemented.
## Contributing
See: [CONTRIBUTING.MD](https://github.com/firebolt-db/firebolt-sqlalchemy/tree/master/CONTRIBUTING.MD)