Install & Compatibility
Where this runs
tested against v0.2.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
py 3.13
✕ build_error
✓ 2.4s
129MB installed
● package 129MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
read_sql
✓ from connectorx import read_sql
This example demonstrates how to use `connectorx.read_sql` to fetch data from a database into a Pandas DataFrame. Remember to replace the placeholder connection string with your actual database credentials and ensure `pandas` is installed. For a runnable example, set the `CX_DB_CONNECTION_STRING` environment variable to a valid database connection string.
import connectorx as cx
import pandas as pd
import os
# Example PostgreSQL connection string
# Replace with your actual database connection string
DB_CONNECTION_STRING = os.environ.get('CX_DB_CONNECTION_STRING', 'postgresql://user:password@host:5432/database')
if DB_CONNECTION_STRING == 'postgresql://user:password@host:5432/database':
print("Warning: Please set CX_DB_CONNECTION_STRING environment variable for a real database connection.")
print("Using a dummy connection string, this example might not run without a database.")
# For a runnable dummy, you might use SQLite in-memory, but ConnectorX doesn't directly support that
# The primary use case is external DBs.
exit(1) # Exit if not configured, as it won't connect without a real string
query = "SELECT id, name FROM my_table WHERE id < 10"
try:
df = cx.read_sql(DB_CONNECTION_STRING, query, return_type="pandas")
print("Successfully read data:")
print(df.head())
except Exception as e:
print(f"An error occurred: {e}")
print("Ensure your database connection string and query are correct, and the database is accessible.")
Debug
Known issues
breakingConnectorX now requires Python 3.10 or higher. Users on older Python versions (3.9 and below) will not be able to install or run the latest versions.fixUpgrade your Python environment to 3.10 or newer.
affects: >=0.4.5 (and earlier 0.4.x releases)
breakingError handling for missing module dependencies has changed. Previously, a `ValueError` might have been raised; it is now `ModuleNotFoundError`.fixUpdate `except` blocks to catch `ModuleNotFoundError` for cases where optional dependencies (like pandas, polars, pyarrow) might be missing for the specified `return_type`.
affects: >=0.4.0
gotchaConnectorX's core functionality relies on optional dependencies (pandas, polars, pyarrow) based on the `return_type` parameter. If you request `return_type="pandas"` without `pandas` installed, it will fail.fixInstall the necessary optional dependencies using `pip install "connectorx[pandas]"`, `"connectorx[polars]"`, or `"connectorx[arrow]"` depending on your required return type.
affects: All versions
gotchaInternal changes related to Arrow libraries (e.g., removal of `arrow2` in v0.4.2, and subsequent `pyarrow` bumps) may affect advanced users who rely on specific Arrow version compatibility or internal structures. This can lead to unexpected type conversions or performance regressions if not carefully managed with existing Arrow-based workflows.fixReview your `pyarrow` version dependencies. Ensure compatibility with the `pyarrow` version bundled or expected by ConnectorX, especially if you manually manage Arrow data within your application.
affects: >=0.4.2
gotchaConnectorX's connection strings are strict and database-specific. Minor syntax errors (e.g., missing slashes, incorrect port, invalid parameters) will prevent connection without clear specific error messages, often resulting in generic connection failures.fixAlways double-check your connection string format against the ConnectorX documentation for your specific database (e.g., PostgreSQL, MySQL, MSSQL) to ensure correctness. Test connectivity with simpler tools if issues persist.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'connectorx.connectorx_python'
This error occurs when the connectorx package is installed, but its core Rust extension module (`connectorx_python`) cannot be found or loaded, often due to an incompatible Python version, operating system, or architecture for which pre-built wheels are not available, or an incomplete installation.
fixEnsure you are using a Python version and system architecture (e.g., x86_64 Linux/Windows, specific macOS versions) for which ConnectorX provides pre-built binary wheels on PyPI. If no wheel is available, you may need to compile from source, which requires installing Rust. Check the official ConnectorX GitHub releases or PyPI for compatibility notes.
RuntimeError: Timed out in bb8
This error indicates that the attempt to connect to the database timed out. Common causes include incorrect connection string parameters (host, port, username, password), network issues, firewall restrictions preventing the connection, or the database server being unavailable or overloaded. For MS SQL Server, specific driver parameters might also be missing.
fixDouble-check your database connection string for accuracy. Verify network connectivity to the database server and ensure no firewalls are blocking the connection. For MS SQL Server connections, consider adding specific driver parameters like `?driver=ODBC+Driver+17+for+SQL+Server&encrypt=true` to the connection string.
AttributeError: type object 'DataFrame' has no attribute 'from_arrow'
This AttributeError typically arises from a version incompatibility between ConnectorX and the specific version of Polars or Pandas installed. ConnectorX uses Arrow internally for efficient data transfer, and if the DataFrame library's API for Arrow conversion (e.g., `from_arrow`) changes, this error can occur.
fixAdjust the versions of your Polars or Pandas library to be compatible with your installed ConnectorX version. Consult the ConnectorX documentation or GitHub issues for known compatible versions. Downgrading or upgrading either library might resolve the conflict.
No matching distribution found for connectorx
This error occurs during installation when `pip` cannot find a pre-compiled wheel package for your specific combination of operating system, Python version, and processor architecture on PyPI. This is particularly common for newer Python versions or less common hardware (like ARM-based systems) for which wheels may not have been published yet.
fixTry installing a slightly older version of ConnectorX for which compatible wheels exist, or consider using a Python version known to have pre-built wheels available for your system (e.g., Python 3.9 or 3.10). If necessary, you might have to build ConnectorX from source, which requires a Rust development environment to be set up.
Upgrade
Version history
0.4.5latest on PyPI · released Jan 18, 2026
Audit
Dependencies
pandasoptionalRequired for `return_type="pandas"`.
polarsoptionalRequired for `return_type="polars"`.
pyarrowoptionalRequired for `return_type="arrow"`.