Install & Compatibility
Where this runs
tested against v2.1.16 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.937s · 73.4MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 9.1s · import 0.867s · 74MB
75MB installed
● package 75MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
redshift_connector
✓ import redshift_connector
The common module name to import is `redshift_connector`.
This quickstart demonstrates how to connect to an Amazon Redshift cluster, create a cursor, execute a simple SQL query, fetch the results, and then close the connection. It's recommended to use environment variables for sensitive credentials.
import redshift_connector
import os
try:
# Connect to Redshift cluster using environment variables for credentials
conn = redshift_connector.connect(
host=os.environ.get('REDSHIFT_HOST', 'your-redshift-cluster.example.com'),
database=os.environ.get('REDSHIFT_DB', 'dev'),
port=int(os.environ.get('REDSHIFT_PORT', '5439')),
user=os.environ.get('REDSHIFT_USER', 'awsuser'),
password=os.environ.get('REDSHIFT_PASSWORD', 'your_password_here')
)
# Create a Cursor object
cursor = conn.cursor()
# Execute a query
cursor.execute("SELECT 1 as id, 'Hello, Redshift!' as message;")
# Retrieve the query result set
result = cursor.fetchall()
print("Query Result:", result)
# Close the cursor and connection
cursor.close()
conn.close()
except Exception as e:
print(f"An error occurred: {e}")
Debug
Known issues
breakingA security vulnerability (CVE-2025-5279) existed in versions 2.0.872 through 2.1.6, where the `BrowserAzureOAuth2CredentialsProvider` plugin skipped SSL certificate validation for the Identity Provider (IdP). This could allow an actor to intercept token exchange.fixUpgrade to `redshift-connector` version 2.1.7 or later to address this issue.
affects: >=2.0.872, <=2.1.6
gotchaAutocommit is `OFF` by default, adhering to the Python DB-API specification. Transactions must be explicitly committed for changes to persist.fixSet `conn.autocommit = True` after connecting, or explicitly call `conn.commit()` after executing statements that modify data.
affects: All versions
gotchaNetwork connectivity issues, including timeouts, are common, especially when connecting from outside an Amazon EC2 instance or running long-duration queries. This can be due to firewall rules, VPC configurations, or client-side TCP/IP timeout settings.fixEnsure Redshift cluster security groups and network ACLs allow inbound/outbound traffic on the Redshift port (default 5439). Increase client system TCP/IP timeout values for long-running queries or idle connections.
affects: All versions
gotchaFor loading large amounts of data into Redshift, using individual `INSERT` statements can be prohibitively slow and expensive.fixStrongly prefer using the `COPY` command with Amazon S3 staging for bulk data loads. The `redshift-connector` supports this method.
affects: All versions
deprecatedAmazon Redshift is ending support for creating new Python User-Defined Functions (UDFs) starting with Patch 198. Existing Python UDFs will continue to function but will be fully unsupported after June 30, 2026.fixMigrate existing Python UDFs to alternative solutions before June 30, 2026. For new functionality, consider SQL UDFs or other data processing patterns.
affects: Redshift clusters on Patch 198 onwards; existing UDFs after June 30, 2026
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'redshift_connector'
The 'redshift-connector' package is not installed in the Python environment where the script is being executed.
fixpip install redshift-connector
redshift_connector.Error.OperationalError: could not connect to server: Connection refused
The Redshift cluster is unreachable, likely due to incorrect host/port in the connection string, network configuration, or firewall rules blocking access.
fixEnsure the host, port, user, password, and database parameters passed to redshift_connector.connect() are correct, and verify network access (security groups, NACLs) to the Redshift cluster from your environment.
redshift_connector.Error.DatabaseError: FATAL: password authentication failed for user "your_user"
The provided username or password for connecting to Redshift is incorrect, or the specified user lacks the necessary database permissions.
fixVerify the username and password used in the redshift_connector.connect() call are correct and that the user has appropriate permissions in Redshift.
redshift_connector.Error.DatabaseError: InvalidToken
The AWS IAM credentials used for authentication are invalid, expired, or the associated IAM role lacks the 'redshift:GetClusterCredentials' permission.
fixEnsure your AWS credentials are valid and correctly configured for IAM authentication with redshift_connector.connect(), and confirm the IAM role has 'redshift:GetClusterCredentials' permission.
OperationalError: Could not connect to host=..., port=...: connection timeout
The Python environment cannot establish a network connection to the specified Redshift host and port, often due to incorrect host/port, network configuration, or firewall rules.
fixVerify the Redshift cluster's hostname and port. Ensure your security groups, network ACLs, and local firewalls allow outbound connections to the Redshift cluster on the specified port.
Upgrade
Version history
2.1.16latest on PyPI · released Aug 3, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.6 or newer.
pandasoptionalOptional, for integration with pandas DataFrames.
numpyoptionalOptional, for integration with NumPy arrays.