Install & Compatibility
Where this runs
tested against v1.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.683s · 67.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 4.1s · import 0.605s · 69MB
64MB installed
● package 64MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_engine
✓ from sqlalchemy import create_engine, text
StarRocks-specific types
✓ from starrocks import INTEGER, STRING, ARRAY, ...
Import StarRocks-specific data types and table properties for ORM declarative models or SQLAlchemy Core definitions.
This quickstart demonstrates how to establish a connection to a StarRocks database using SQLAlchemy's `create_engine` and execute a simple query. It uses environment variables for secure credential management. Ensure you have a running StarRocks cluster and a database configured.
import os
from sqlalchemy import create_engine, text
# Configure connection details via environment variables
STARROCKS_USER = os.environ.get('STARROCKS_USER', 'root')
STARROCKS_PASSWORD = os.environ.get('STARROCKS_PASSWORD', '')
STARROCKS_HOST = os.environ.get('STARROCKS_HOST', 'localhost')
STARROCKS_PORT = os.environ.get('STARROCKS_PORT', '9030')
STARROCKS_DATABASE = os.environ.get('STARROCKS_DATABASE', 'mydatabase')
# Construct connection string
connection_string = (
f"starrocks://{STARROCKS_USER}:" # User and optional password
f"{STARROCKS_PASSWORD}@{STARROCKS_HOST}:{STARROCKS_PORT}/"
f"{STARROCKS_DATABASE}"
)
# Create a SQLAlchemy engine
engine = create_engine(connection_string)
try:
# Establish a connection and execute a basic query
with engine.connect() as connection:
print("Connection successful!")
# Ensure 'mytable' exists in 'mydatabase' for this example
result = connection.execute(text("SELECT 1 + 1")).scalar()
print(f"Query result: {result}")
# Example: Fetching data from a table (uncomment and replace if 'mytable' exists)
# rows = connection.execute(text("SELECT * FROM mytable LIMIT 2")).fetchall()
# print(rows)
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingThe `starrocks` Python client currently supports SQLAlchemy versions `>=1.4` but strictly less than `2.0`. Attempting to use `starrocks` with SQLAlchemy 2.0 (e.g., `sqlalchemy>=2.0.0`) will result in incompatibility issues.fixEnsure `SQLAlchemy` is pinned to a version less than 2.0, for example, `pip install "SQLAlchemy<2"`. Monitor the official StarRocks Python client repository for updates on SQLAlchemy 2.0 compatibility.
affects: <1.3.x (with SQLAlchemy 2.0), 1.3.x (with SQLAlchemy 2.0)
gotchaFor basic synchronous StarRocks connections, an underlying MySQL-compatible DBAPI driver (like `mysqlclient` or `PyMySQL`) might be required, even if not explicitly listed as a direct dependency of the `starrocks` package. If you encounter errors related to `MySQLdb` or similar, install one of these drivers.fixInstall a suitable DBAPI driver: `pip install mysqlclient` or `pip install PyMySQL`.
affects: All versions
gotchaThe library officially supports Python versions `3.10` through `3.14`. Using it with Python `3.15` or newer may lead to unexpected behavior or incompatibilities.fixEnsure your Python environment is within the supported range `Python >= 3.10, <= 3.14`.
affects: All versions
breakingWhen upgrading StarRocks *server* versions, be aware of strict downgrade limitations. For instance, downgrading from StarRocks 4.1 to any 4.0 version below 4.0.6 is not supported due to internal changes in data layout. Similar restrictions apply for downgrading from 4.0 to versions below 3.5.2.fixAlways consult the official StarRocks release notes and upgrade/downgrade guides for your specific server versions to avoid metadata incompatibility and potential cluster crashes. These warnings primarily apply to the StarRocks server and its metadata, not directly the Python client, but impact overall system stability.
affects: StarRocks server versions 4.0, 4.1 and later
gotchaConnecting to and managing external catalogs (e.g., Iceberg) via the SQLAlchemy dialect might have limitations or require specific connection string formats. An open GitHub issue indicates challenges with specifying catalogs directly and reflecting tables.fixRefer to the latest StarRocks documentation and GitHub issues for current best practices and workarounds when integrating with external catalogs. The format `starrocks://<User>:<Password>@<Host>:<Port>/[<Catalog>.]<Database>` supports specifying a catalog.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'starrocks'
The main Python package for StarRocks integration with SQLAlchemy is `starrocks-sqlalchemy`, not `starrocks`.
fixInstall the correct package: `pip install starrocks-sqlalchemy`
sqlalchemy.exc.NoSuchModuleError: Can't load plugin: sqlalchemy.dialects:starrocks
The `starrocks-sqlalchemy` package, which registers the 'starrocks' dialect with SQLAlchemy, is either not installed or not correctly recognized by the current Python environment.
fixEnsure the `starrocks-sqlalchemy` package is installed: `pip install starrocks-sqlalchemy`
sqlalchemy.exc.OperationalError: (starrocks.driver.exceptions.StarRocksDriverError) (2000) Could not connect to StarRocks at host:port
The provided connection parameters in the SQLAlchemy URL are incorrect, or the StarRocks server is not running or accessible from the client.
fixVerify the StarRocks server is running and accessible, then double-check the connection string details (host, port, user, password, database).
starrocks.driver.exceptions.StarRocksDriverError: (1064) You have an error in your SQL syntax; check the manual that corresponds to your StarRocks server version for the right syntax to use near '...' at line ...
The SQL query executed contains syntax errors that are not compliant with the StarRocks SQL dialect or version being used.
fixReview the SQL statement for correct syntax, paying attention to StarRocks-specific functions and data types, and consult the StarRocks documentation.
Upgrade
Version history
1.3.3latest on PyPI · released Jan 14, 2026
Audit
Dependencies
SQLAlchemyrequiredCore dependency for database interaction.
AlembicoptionalOptional for database schema migrations.
asyncmyoptionalRequired for asynchronous StarRocks connections.
pyarrowoptionalRequired for Python UDF functionality in StarRocks.