Connect to Databend using Python with our official drivers supporting both synchronous and asynchronous operations.
Quick Start
Choose your preferred approach:
| Package | Best For | Installation |
|---|---|---|
| databend-driver | Direct database operations, async/await | pip install databend-driver |
| databend-sqlalchemy | ORM integration, existing SQLAlchemy apps | pip install databend-sqlalchemy |
Connection String: See Drivers Overview for DSN format and examples.
databend-driver (Recommended)
Features
- ✅ Native Performance: Direct connection to Databend
- ✅ Async/Sync Support: Choose your programming style
- ✅ PEP 249 Compatible: Standard Python DB API
- ✅ Type Safety: Full Python type mapping
Synchronous Usage
from databend_driver import BlockingDatabendClient
# Connect and execute
client = BlockingDatabendClient('<your-dsn>')
cursor = client.cursor()
# DDL: Create table
cursor.execute("CREATE TABLE users (id INT, name STRING)")
# Write: Insert data
cursor.execute("INSERT INTO users VALUES (?, ?)", (1, 'Alice'))
# Query: Read data
# Query: Read data
cursor.execute("SELECT * FROM users")
# Get column names
# cursor.description returns a list of tuples, where the first element is the column name
print(f"Columns: {[desc[0] for desc in cursor.description]}")
for row in cursor.fetchall():
# row is a databend_driver.Row object
# Access by column name
print(f"id: {row['id']}, name: {row['name']}")
cursor.close()
Working with Row Objects
The Row object supports multiple access patterns and methods:
for row in cursor.fetchall():
# 1. Access by column name (Recommended)
print(f"Name: {row['name']}")
# 2. Access by index
print(f"First column: {row[0]}")
# 3. Convert to tuple
print(f"Values: {row.values()}")
# 4. Explicit methods
print(row.get_by_field('name'))
print(row.get_by_index(0))
Asynchronous Usage
import asyncio
from databend_driver import AsyncDatabendClient
async def main():
client = AsyncDatabendClient('<your-dsn>')
conn = await client.get_conn()
# DDL: Create table
await conn.exec("CREATE TABLE users (id INT, name STRING)")
# Write: Insert data
await conn.exec("INSERT INTO users VALUES (?, ?)", (1, 'Alice'))
# Query: Read data
rows = await conn.query_iter("SELECT * FROM users")
async for row in rows:
print(row.values())
await conn.close()
asyncio.run(main())
databend-sqlalchemy
For SQLAlchemy ORM integration:
from sqlalchemy import create_engine, text
engine = create_engine('<your-dsn>')
with engine.connect() as conn:
result = conn.execute(text("SELECT 1"))
print(result.fetchall())
Data Type Mappings
| Databend | Python | Notes |
|---|---|---|
| Numeric Types | ||
BOOLEAN | bool | |
TINYINT | int | |
SMALLINT | int | |
INT | int | |
BIGINT | int | |
FLOAT | float | |
DOUBLE | float | |
DECIMAL | decimal.Decimal | Precision preserved |
| Date/Time | ||
DATE | datetime.date | |
TIMESTAMP | datetime.datetime | |
INTERVAL | datetime.timedelta | |
| Text/Binary | ||
VARCHAR | str | UTF-8 encoded |
BINARY | bytes | |
| Complex Types | ||
ARRAY | list | Nested structures supported |
TUPLE | tuple | |
MAP | dict | |
VARIANT | str | JSON-encoded |
BITMAP | str | Base64-encoded |
GEOMETRY | str | WKT format |
Resources
- PyPI: databend-driver • databend-sqlalchemy
- GitHub: databend-driver • databend-sqlalchemy