Installation¶
Python Package¶
pip install "jdbc4py[dataframe]" # pandas, Polars, DuckDB + the Arrow bulk path
pip install "jdbc4py[arrow]" # Arrow only
pip install jdbc4py # core (row-by-row fetch)
The wheel bundles the prebuilt Arrow helper JAR, so there's no JDK or build step at install time — just a Java 11+ runtime (see below). You still supply your own JDBC driver JAR for each database (see driver-management.md).
To work on jdbc4py itself, install from source instead — see Development Install at the bottom of this page.
Java Requirements¶
jdbc4py requires Java 11 or newer. A JRE is enough — you only need a JDK if you're building the helper JAR from source.
Check your Java version:
If Java isn't installed, get a build from Adoptium — the Eclipse Temurin builds are free and work on all platforms.
Setting JAVA_HOME¶
jdbc4py finds the JVM via JAVA_HOME first, then PATH. If connect() raises a JVMError mentioning Java detection, set JAVA_HOME explicitly:
# macOS
export JAVA_HOME=$(/usr/libexec/java_home)
# Linux (adjust path to match your install)
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
# Windows (PowerShell)
$env:JAVA_HOME = "C:\Program Files\Eclipse Adoptium\jdk-17.0.9.9-hotspot"
Add this to your shell profile (~/.bashrc, ~/.zshrc, etc.) to make it permanent.
JDBC Driver Setup¶
jdbc4py doesn't bundle JDBC drivers. You download the JAR for your database and tell jdbc4py where to find it. There are three ways to do this.
Option 1: Drop it in the drivers directory¶
jdbc4py automatically scans drivers/<engine>/ relative to the project root:
This is the simplest approach for local development.
Option 2: Pass it directly¶
conn = connect(
engine="postgres",
host="localhost",
database="mydb",
user="me",
password="secret",
jar="path/to/postgresql-42.7.10.jar",
)
Use this when you want explicit control or when the JAR lives outside the project.
Option 3: Environment variable¶
# Colon-separated on Unix, semicolon-separated on Windows
export JDBC4PY_DRIVER_PATHS="/opt/jdbc-drivers:/usr/local/jdbc"
jdbc4py scans every directory in JDBC4PY_DRIVER_PATHS for matching JARs. See driver-management.md for security constraints on this variable.
Where to get JARs¶
| Database | Download |
|---|---|
| PostgreSQL | https://jdbc.postgresql.org/download/ |
| MySQL | https://dev.mysql.com/downloads/connector/j/ |
| SQL Server | https://learn.microsoft.com/en-us/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server |
| Oracle | https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html |
| ClickHouse | https://github.com/ClickHouse/clickhouse-java/releases |
| Trino | https://trino.io/docs/current/client/jdbc.html |
| Snowflake | https://docs.snowflake.com/en/developer-guide/jdbc/jdbc-download |
| Databricks | https://www.databricks.com/spark/jdbc-drivers-download |
Verifying the Install¶
from jdbc4py import connect
with connect(
engine="postgres",
host="localhost",
database="mydb",
user="me",
password="secret",
) as conn:
with conn.cursor() as cur:
cur.execute("SELECT 1")
print(cur.fetchone()) # (1,)
If that works, you're set.
Common errors:
JVMError: could not find Java— setJAVA_HOMEas described aboveDriverNotFoundError— the JAR isn't where jdbc4py is looking; check the pathDatabaseError: Connection refused— the database isn't running or the host/port is wrong
Development Install¶
git clone https://github.com/ryuk-me/jdbc4py
cd jdbc4py
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,dataframe]"
Build the Java helper JAR (required for Arrow bulk reads and optimized batch fetches):
This requires a JDK (Java 11+) and network access (it downloads dependency JARs from Maven Central); Maven itself is not needed — the script uses javac/jar. The built JAR lands at java/jdbc4py-helper/dist/jdbc4py-helper.jar and is picked up automatically by jdbc4py.
Run the tests: