Install & Compatibility
Where this runs
tested against v1.0.0 · 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.915 runs
installs and imports cleanly · install 0.0s · import 0.663s · 98.6MB
glibcpy 3.10–3.915 runs
installs and imports cleanly · install 4.9s · import 0.617s · 97MB
69MB installed
● package 69MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_engine
✓ from sqlalchemy import create_engine
✗ import sqlalchemy as sa
engine = sa.create_engine(...)
This quickstart demonstrates how to establish a connection to an Amazon Redshift database using `sqlalchemy-redshift` and perform a simple query. It uses environment variables for credentials and connects via the `psycopg2` driver. Remember to install an underlying DBAPI driver like `psycopg2-binary` or `redshift_connector` alongside `sqlalchemy-redshift`.
import sqlalchemy as sa
import os
# Ensure either 'redshift_connector' or 'psycopg2' is installed
# e.g., pip install sqlalchemy-redshift psycopg2-binary
# Redshift connection details from environment variables
REDSHIFT_USER = os.environ.get("REDSHIFT_USER", "your_username")
REDSHIFT_PASSWORD = os.environ.get("REDSHIFT_PASSWORD", "your_password")
REDSHIFT_HOST = os.environ.get("REDSHIFT_HOST", "your_redshift_host.amazonaws.com")
REDSHIFT_PORT = os.environ.get("REDSHIFT_PORT", "5439")
REDSHIFT_DB = os.environ.get("REDSHIFT_DB", "your_database_name")
# Construct connection string using psycopg2 driver (can be 'redshift_connector')
connection_string = (
f"redshift+psycopg2://{REDSHIFT_USER}:{REDSHIFT_PASSWORD}@"
f"{REDSHIFT_HOST}:{REDSHIFT_PORT}/{REDSHIFT_DB}"
)
try:
engine = sa.create_engine(connection_string)
with engine.connect() as connection:
# Perform a simple query to verify connection
result = connection.execute(sa.text("SELECT 1 as id, 'hello' as message")).fetchone()
if result:
print(f"Connection successful! Result: ID={result.id}, Message='{result.message}'")
else:
print("Connection successful, but no result returned for test query.")
except Exception as e:
print(f"Error connecting to Redshift: {e}")
Debug
Known issues
breakingThe package name was changed from `redshift_sqlalchemy` to `sqlalchemy_redshift` in version 0.4.0. Older applications may need to update their `pip install` commands and import statements.fixUpdate `pip install redshift-sqlalchemy` to `pip install sqlalchemy-redshift` and adjust any direct imports if they were used.
affects: 0.4.0 and earlier
breakingSupport for Python 2.7 was dropped in version 0.8.8. Users on Python 2.7 will need to upgrade to Python 3.4+ or use an older version of `sqlalchemy-redshift`.fixUpgrade your Python environment to Python 3.4 or newer.
affects: 0.8.8+
gotchaThis dialect requires an external DBAPI driver (`psycopg2` or `redshift_connector`) to function, but it does not install either of them automatically. You must install one separately.fixInstall `psycopg2-binary` (for convenience) or `redshift_connector` explicitly: `pip install sqlalchemy-redshift psycopg2-binary` or `pip install sqlalchemy-redshift redshift_connector`.
affects: All versions
gotchaWhen using SQLAlchemy's ORM with Redshift tables, a primary key is required for mapped classes, even if the underlying Redshift table lacks one. Attempting to reflect a table without a primary key will cause issues.fixWhen defining your SQLAlchemy model for a Redshift table without a primary key, you can designate a column to act as the primary key using `__mapper_args__ = {'primary_key': [your_column_name]}`. affects: All versions
gotchaWhen executing raw SQL statements that involve schema or table names (e.g., `GRANT SELECT ON schema.table TO user`), SQLAlchemy's default parameter binding might quote these identifiers, leading to syntax errors in Redshift.fixUse f-strings or `sqlalchemy.text()` with direct string formatting (if identifiers are trusted) for such statements, or explicitly use `sqlalchemy.sql.text()` with `.bindparams()` and then use the `AsIs` construct from `psycopg2` if dealing directly with DBAPI. Be cautious of SQL injection risks when directly formatting SQL strings.
affects: All versions
Upgrade
Version history
1.0.0latest on PyPI · released Apr 28, 2026
Audit
Dependencies
sqlalchemyrequiredCore dependency for database interaction and ORM capabilities.
psycopg2optionalRequired DBAPI driver to connect to Redshift. User must choose this or 'redshift_connector'.
redshift_connectoroptionalRequired DBAPI driver to connect to Redshift. User must choose this or 'psycopg2'. Provides native IAM auth and Redshift-specific data types (>= 0.8.6).