Skip to main content

Connect to Databend Using Python

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