Install & Compatibility
Where this runs
tested against v1.1.10 · 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.95 runs
installs and imports cleanly · install 0.0s · import 0.678s · 47.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 4.1s · import 0.626s · 45MB
46MB installed
● package 46MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_engine
✓ from sqlalchemy import create_engine
text
✓ from sqlalchemy import text
This quickstart demonstrates how to establish a connection to Apache Drill using the `drill+sadrill` (REST API) dialect and execute a simple query. The example uses environment variables for configuration, which is recommended for production environments. Ensure Apache Drill is running and accessible from where this code is executed. For JDBC or ODBC connections, additional drivers and optional Python packages are required.
from sqlalchemy import create_engine, text
import os
# For REST API connection
# Adjust host and port as per your Drill setup
# Use environment variables for sensitive data in production
# Example for local Drill embedded mode (drill+sadrill)
DR_HOST = os.environ.get('DRILL_HOST', 'localhost')
DR_PORT = os.environ.get('DRILL_REST_PORT', '8047')
DR_PLUGIN = os.environ.get('DRILL_STORAGE_PLUGIN', 'dfs')
DR_USE_SSL = os.environ.get('DRILL_USE_SSL', 'False').lower() == 'true'
connection_string = f"drill+sadrill://{DR_HOST}:{DR_PORT}/{DR_PLUGIN}?use_ssl={DR_USE_SSL}"
try:
engine = create_engine(connection_string)
with engine.connect() as connection:
result = connection.execute(text("SELECT * FROM INFORMATION_SCHEMA.CATALOGS LIMIT 5"))
print("Successfully connected to Apache Drill via REST API.")
print("First 5 catalogs:")
for row in result:
print(row)
except Exception as e:
print(f"Failed to connect to Apache Drill: {e}")
print("Ensure Apache Drill is running and accessible at the specified host/port.")
print("For JDBC or ODBC, ensure required optional dependencies and drivers are installed and configured.")
Debug
Known issues
breakingWhen connecting to Apache Drill versions prior to 1.19 via the REST API (drill+sadrill), all data values are serialized to JSON strings. This means that numerical or temporal data will be returned as strings and require manual typecasting in your application.fixUpgrade Apache Drill to version 1.19 or newer, or explicitly cast string results to their native types in your application code for older Drill versions.
affects: <1.19 (Drill version)
gotchaJDBC connections require manual setup of JPype and the Drill JDBC driver. The `sqlalchemy-drill` library does not start the JVM or manage JDBC driver paths for you. Users must explicitly call `jpype.startJVM()` and set environment variables like `DRILL_JDBC_DRIVER_PATH` and `DRILL_JDBC_JAR_NAME`.fixBefore creating the SQLAlchemy engine with `drill+jdbc://`, ensure `JayDeBeApi` and `jPype1` are installed, the Drill JDBC driver is downloaded, and the JVM is started and configured correctly in your Python code.
affects: All versions (when using JDBC)
gotchaOptional dependencies (`JayDeBeApi`, `jPype1`, `pyodbc`) for JDBC and ODBC connectivity are NOT installed by default with `pip install sqlalchemy-drill`. Attempting to use JDBC or ODBC dialects without these packages will result in connection errors.fixInstall the necessary optional packages manually (e.g., `pip install sqlalchemy-drill[jdbc]` or `pip install JayDeBeApi jPype1`, `pip install pyodbc`) if you intend to use JDBC or ODBC connections.
affects: All versions
gotchaVersions prior to `1.1.2` had issues with impersonation for Drill 1.20, potentially leading to incorrect user context for queries.fixUpgrade to `sqlalchemy-drill` version `1.1.2` or later to ensure correct impersonation functionality with Drill 1.20+.
affects: <1.1.2
gotchaEarly versions (e.g., prior to `1.1.7` and `1.18`) contained bugs in DB-API compliance regarding method delegation and return values, which could lead to unexpected behavior during query execution or result fetching.fixUpgrade to `sqlalchemy-drill` version `1.1.10` or the latest stable version to benefit from various DB-API compliance and data handling bug fixes.
affects: <1.1.7, <1.18
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'sqlalchemy_drill'
The 'sqlalchemy-drill' Python package is not installed in the current environment or is misspelled in the import statement.
fixInstall the package using pip: `pip install sqlalchemy-drill`
Can't load plugin: sqlalchemy.dialects:drill
SQLAlchemy cannot find the entry point for the 'drill' dialect, indicating that 'sqlalchemy-drill' might be improperly installed or its dialect registration is corrupted.
fixReinstall 'sqlalchemy-drill' to ensure proper dialect registration: `pip uninstall sqlalchemy-drill && pip install sqlalchemy-drill`
ModuleNotFoundError: No module named 'pyodbc'
You are attempting to connect to Apache Drill via ODBC using 'sqlalchemy-drill', but the 'pyodbc' driver (an optional dependency) is not installed.
fixInstall 'sqlalchemy-drill' with the ODBC optional dependency: `pip install sqlalchemy-drill[odbc]`
ModuleNotFoundError: No module named 'jaydebec'
You are attempting to connect to Apache Drill via JDBC using 'sqlalchemy-drill', but the 'JayDeBeC' driver (an optional dependency) is not installed.
fixInstall 'sqlalchemy-drill' with the JDBC optional dependency: `pip install sqlalchemy-drill[jdbc]`
Upgrade
Version history
1.1.10latest on PyPI · released Feb 5, 2026
Audit
Dependencies
JayDeBeApioptionalRequired for JDBC connections to Apache Drill. Used in conjunction with jPype.
jPype1optionalRequired for JDBC connections to Apache Drill to manage the JVM and JDBC driver. Specific version 0.6.3 or compatible is noted.
pyodbcoptionalRequired for ODBC connections to Apache Drill.