Registry /
database / sqlalchemy-singlestoredb
Install & Compatibility
Where this runs
tested against v1.2.1 · 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.686s · 55.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 5.4s · import 0.636s · 59MB
57MB installed
● package 57MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_engine
✓ from sqlalchemy import create_engine
✗ from sqlalchemy_singlestoredb import create_engine
The dialect registers itself with SQLAlchemy; `create_engine` is imported from `sqlalchemy`.
text
✓ from sqlalchemy import text
Used for executing raw SQL queries within SQLAlchemy.
This quickstart demonstrates how to establish a connection to SingleStoreDB using SQLAlchemy, create a table, insert data, and select data. It uses environment variables for secure connection string management and handles basic error reporting.
import os
from sqlalchemy import create_engine, text
# Get connection details from environment variables for security
user = os.environ.get('SINGLESTORE_USER', 'admin')
password = os.environ.get('SINGLESTORE_PASSWORD', 'password')
host = os.environ.get('SINGLESTORE_HOST', '127.0.0.1')
port = os.environ.get('SINGLESTORE_PORT', '3306')
database = os.environ.get('SINGLESTORE_DATABASE', 'test_db')
# Construct connection URL
connection_url = f"singlestoredb://{user}:{password}@{host}:{port}/{database}"
try:
# Create an engine instance
engine = create_engine(connection_url)
# Establish a connection and execute a simple query
with engine.connect() as connection:
# Example: Create a table if it doesn't exist
connection.execute(text("CREATE TABLE IF NOT EXISTS my_table (id INT, name VARCHAR(255))"))
print("Table 'my_table' ensured.")
# Example: Insert data
connection.execute(text("INSERT INTO my_table (id, name) VALUES (:id, :name)"), {"id": 1, "name": "Alice"})
connection.execute(text("INSERT INTO my_table (id, name) VALUES (:id, :name)"), {"id": 2, "name": "Bob"})
print("Data inserted.")
# Example: Select data
result = connection.execute(text("SELECT id, name FROM my_table"))
for row in result:
print(f"ID: {row.id}, Name: {row.name}")
# Commit the changes (if not in autocommit mode, depends on dialect/DB config)
connection.commit()
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
gotchaThe `client_found_rows` connection parameter was changed to `True` by default in v1.1.3. This affects how `rowcount` is reported for DML statements (INSERT, UPDATE, DELETE), matching MySQL's `CLIENT_FOUND_ROWS` behavior. Applications relying on the old `rowcount` behavior might see different results.fixReview existing code that inspects `rowcount` after DML operations. If the old behavior is desired, explicitly set `client_found_rows=False` in the connection URL or `connect_args`.
affects: <1.1.3
breakingEarlier versions (prior to v1.1.2) had issues handling special characters in passwords within the connection URL, leading to connection failures. While fixed, upgrading is recommended if you're on an older version and use complex passwords.fixUpgrade to `sqlalchemy-singlestoredb` v1.1.2 or newer. Ensure passwords are URL-encoded if manually constructing connection strings for older versions, though this library should handle it correctly in newer releases.
affects: <1.1.2
gotchaSupport for SQLAlchemy 2.0 was explicitly added in v0.3.0 and further refined in v1.1.1 to fix deprecation warnings. If you're using SQLAlchemy 2.0 with an older version of this dialect, you might encounter deprecation warnings or compatibility issues.fixEnsure you are using `sqlalchemy-singlestoredb` v1.1.1 or newer when working with SQLAlchemy 2.0 to avoid deprecation warnings and benefit from full compatibility.
affects: <0.3.0, <1.1.1 (for SQLAlchemy 2.0 users)
gotchaVersion 1.2.0 introduced `singlestoredb_` prefixed keyword parameters (e.g., `singlestoredb_shard_key`, `singlestoredb_sort_key`) to SQLAlchemy DDL objects. Existing code will continue to work, but to leverage SingleStoreDB-specific features for table creation (like shard/sort keys, persisted columns), these new parameters should be adopted.fixReview the documentation for `sqlalchemy-singlestoredb` to understand and implement the new `singlestoredb_` keyword arguments when defining table structures with SingleStoreDB-specific features.
affects: <1.2.0 (for missing features)
Upgrade
Version history
1.2.1latest on PyPI · released Jan 28, 2026
Audit
Dependencies
sqlalchemyrequiredRequired ORM framework for the dialect.
singlestoredbrequiredThe underlying DB-API 2.0 driver for connecting to SingleStoreDB.