Registry / database / starrocks

starrocks

JSON →
library1.3.3pypypi✓ verified 84d ago

The `starrocks` library provides a Python SQLAlchemy Dialect and an Alembic extension for interacting with StarRocks, a next-generation data platform designed for fast, real-time analytics. It enables developers to leverage SQLAlchemy's ORM and expression language, and manage database schema migrations with Alembic. The project is actively maintained with releases occurring every few months.

pip install starrocks
INSTALL
IMPORT
SIG · STARROCKS
S
starrocks
databasepythonv1.3.3
Install
4.1s avg
Import
644ms
Disk
64MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.683s · 67.1MB
glibc
py 3.103.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.
fix
Ensure `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.
fix
Install 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.
fix
Ensure 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.
fix
Always 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.
fix
Refer 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`.
fix
Install 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.
fix
Ensure 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.
fix
Verify 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.
fix
Review 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.
Agent activity
23 hits · last 30 days
node
20
OpenAI (training)
1
Resources