Install & Compatibility
Where this runs
tested against v2.2.1 · 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.10
✕ build_error
✓ 3.68s
py 3.11
✕ build_error
✓ 3.33s
py 3.12
✕ build_error
✓ 3.08s
py 3.13
✕ build_error
✓ 3.18s
py 3.9
✕ build_error
2/4 runs
43MB installed
● package 43MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
AS400Dialect
✓ from sqlalchemy_jdbcapi import AS400Dialect
✗ from sqlalchemy_jdbcapi.async_dbapi import AsyncConnection
AccessDialect
✓ from sqlalchemy_jdbcapi import AccessDialect
dialects
✓ from sqlalchemy_jdbcapi import dialects
This quickstart demonstrates how to establish a connection to a PostgreSQL database using `sqlalchemy-jdbcapi` via a JDBC driver. It uses `create_engine` with the `jdbcapi+postgresql` dialect. Ensure you have a Java Runtime Environment (JRE) or Java Development Kit (JDK) installed and accessible to JPype, typically by setting the `JAVA_HOME` environment variable. The example includes a basic synchronous query and comments on how to extend for asyncio support.
import os
from sqlalchemy import create_engine, text
# Ensure JAVA_HOME is set for JPype to find a JVM
# Example: os.environ['JAVA_HOME'] = '/path/to/your/jdk'
# Example for PostgreSQL via JDBC
# Replace with your actual database details or environment variables
DB_USER = os.environ.get('JDBC_DB_USER', 'your_user')
DB_PASS = os.environ.get('JDBC_DB_PASS', 'your_password')
DB_HOST = os.environ.get('JDBC_DB_HOST', 'localhost')
DB_PORT = os.environ.get('JDBC_DB_PORT', '5432')
DB_NAME = os.environ.get('JDBC_DB_NAME', 'your_database')
# The dialect string uses 'jdbcapi+' followed by the driver name
# For PostgreSQL, it's 'postgresql'. For MySQL, 'mysql', etc.
jdbc_url = f"jdbcapi+postgresql://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
try:
engine = create_engine(jdbc_url)
with engine.connect() as connection:
result = connection.execute(text("SELECT 1"))
print(f"Connection successful, result: {result.scalar()}")
# Example with asyncio (requires sqlalchemy-jdbcapi>=2.2.1 and asyncpg, aiomysql, etc.)
# from sqlalchemy.ext.asyncio import create_async_engine
# async_jdbc_url = f"jdbcapi+postgresql+asyncpg://{DB_USER}:{DB_PASS}@{DB_HOST}:{DB_PORT}/{DB_NAME}"
# async_engine = create_async_engine(async_jdbc_url)
# async def run_async_query():
# async with async_engine.connect() as conn:
# result = await conn.execute(text("SELECT 2"))
# print(f"Async connection successful, result: {result.scalar()}")
# import asyncio
# asyncio.run(run_async_query())
except Exception as e:
print(f"Error connecting to database: {e}")
finally:
# JPype requires explicit JVM shutdown in some contexts or when done
try:
from jpype import isJVMStarted, shutdownJVM
if isJVMStarted():
shutdownJVM()
print("JVM shut down.")
except ImportError:
pass # JPype might not be installed or available
Debug
Known issues
breakingVersion 2.0.0 of `sqlalchemy-jdbcapi` introduced a complete rewrite of its core infrastructure, transitioning to a native DB-API 2.0 implementation built on JPype. This fundamentally changed how the dialect interacts with databases compared to 1.x versions.fixUpgrade to `sqlalchemy-jdbcapi` 2.x and review all connection URLs and any direct DB-API interactions. Connection strings now typically start with `jdbcapi+<driver_name>://`.
affects: 1.x migrating to 2.x
gotcha`sqlalchemy-jdbcapi` relies on `JPype` for JDBC connectivity, which requires a Java Virtual Machine (JVM) to be present and discoverable on the system. Common issues include `RuntimeError: No JVM shared library found` or `JClassException` for missing Java classes.fixEnsure a compatible JRE/JDK (Java 8 or higher is generally recommended) is installed and that the `JAVA_HOME` environment variable is correctly set to the JDK/JRE installation directory. Alternatively, configure JPype to find the JVM shared library manually if `JAVA_HOME` is not an option.
affects: All 2.x versions
gotchaThe library automatically downloads JDBC drivers from Maven Central by default. This process can fail due to network restrictions (e.g., corporate proxies, firewalls), or if specific driver versions are required but not available or correctly resolved.fixFor network issues, ensure proper proxy settings or allowlist Maven Central URLs. For specific drivers, you can manually provide JDBC JAR files by placing them in a directory specified by the `SQL_ALCHEMY_JDBCAPI_JVM_CLASSPATH` environment variable or using the `jdbcapi.driver_path` argument in `create_engine`.
affects: All 2.x versions
gotchaFull asyncio support, including `AsyncConnection` and `AsyncCursor` classes, was introduced in version 2.2.1. Code attempting to use `await` with `sqlalchemy-jdbcapi` on older versions will fail or operate synchronously.fixUpgrade `sqlalchemy-jdbcapi` to version `2.2.1` or newer to leverage its asyncio capabilities. Ensure that you are also using an appropriate SQLAlchemy async driver (e.g., `asyncpg` for PostgreSQL, `aiomysql` for MySQL) in your connection string (e.g., `jdbcapi+postgresql+asyncpg://...`).
affects: 2.0.0 - 2.2.0
Upgrade
Version history
2.2.1latest on PyPI · released Nov 19, 2025
Audit
Dependencies
JPype1requiredRequired for all JDBC connections and core functionality.
SQLAlchemyrequiredPeer dependency; this library is an SQLAlchemy dialect.
pyodbcoptionalOptional: Required for using ODBC-based connections.