Skip to main content

Python Driver for Databend

Connect to Databend using Python with our official drivers supporting both synchronous and asynchronous operations.

Quick Start

Choose your preferred approach:

PackageBest ForInstallation
databend-driverDirect database operations, async/awaitpip install databend-driver
databend-sqlalchemyORM integration, existing SQLAlchemy appspip install databend-sqlalchemy

Connection String: See Drivers Overview for DSN format and examples.


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
cursor.execute("SELECT * FROM users")
for row in cursor.fetchall():
print(row.values())

cursor.close()

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

DatabendPythonNotes
Numeric Types
BOOLEANbool
TINYINTint
SMALLINTint
INTint
BIGINTint
FLOATfloat
DOUBLEfloat
DECIMALdecimal.DecimalPrecision preserved
Date/Time
DATEdatetime.date
TIMESTAMPdatetime.datetime
INTERVALdatetime.timedelta
Text/Binary
VARCHARstrUTF-8 encoded
BINARYbytes
Complex Types
ARRAYlistNested structures supported
TUPLEtuple
MAPdict
VARIANTstrJSON-encoded
BITMAPstrBase64-encoded
GEOMETRYstrWKT format

Resources