{"id":6894,"library":"starrocks","title":"StarRocks SQLAlchemy Dialect","description":"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.","status":"active","version":"1.3.3","language":"en","source_language":"en","source_url":"https://github.com/starrocks/starrocks.git","tags":["database","sqlalchemy","starrocks","dialect","alembic","orm","olap","analytics"],"install":[{"cmd":"pip install starrocks","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for database interaction.","package":"SQLAlchemy","optional":false},{"reason":"Optional for database schema migrations.","package":"Alembic","optional":true},{"reason":"Required for asynchronous StarRocks connections.","package":"asyncmy","optional":true},{"reason":"Required for Python UDF functionality in StarRocks.","package":"pyarrow","optional":true}],"imports":[{"symbol":"create_engine","correct":"from sqlalchemy import create_engine, text"},{"note":"Import StarRocks-specific data types and table properties for ORM declarative models or SQLAlchemy Core definitions.","symbol":"StarRocks-specific types","correct":"from starrocks import INTEGER, STRING, ARRAY, ..."}],"quickstart":{"code":"import os\nfrom sqlalchemy import create_engine, text\n\n# Configure connection details via environment variables\nSTARROCKS_USER = os.environ.get('STARROCKS_USER', 'root')\nSTARROCKS_PASSWORD = os.environ.get('STARROCKS_PASSWORD', '')\nSTARROCKS_HOST = os.environ.get('STARROCKS_HOST', 'localhost')\nSTARROCKS_PORT = os.environ.get('STARROCKS_PORT', '9030')\nSTARROCKS_DATABASE = os.environ.get('STARROCKS_DATABASE', 'mydatabase')\n\n# Construct connection string\nconnection_string = (\n    f\"starrocks://{STARROCKS_USER}:\"  # User and optional password\n    f\"{STARROCKS_PASSWORD}@{STARROCKS_HOST}:{STARROCKS_PORT}/\"\n    f\"{STARROCKS_DATABASE}\"\n)\n\n# Create a SQLAlchemy engine\nengine = create_engine(connection_string)\n\ntry:\n    # Establish a connection and execute a basic query\n    with engine.connect() as connection:\n        print(\"Connection successful!\")\n        # Ensure 'mytable' exists in 'mydatabase' for this example\n        result = connection.execute(text(\"SELECT 1 + 1\")).scalar()\n        print(f\"Query result: {result}\")\n        \n        # Example: Fetching data from a table (uncomment and replace if 'mytable' exists)\n        # rows = connection.execute(text(\"SELECT * FROM mytable LIMIT 2\")).fetchall()\n        # print(rows)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"breaking","affected_versions":"<1.3.x (with SQLAlchemy 2.0), 1.3.x (with SQLAlchemy 2.0)"},{"fix":"Install a suitable DBAPI driver: `pip install mysqlclient` or `pip install PyMySQL`.","message":"For 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment is within the supported range `Python >= 3.10, <= 3.14`.","message":"The 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"When 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.","severity":"breaking","affected_versions":"StarRocks server versions 4.0, 4.1 and later"},{"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.","message":"Connecting 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z","problems":[]}