Registry / database / sqlalchemy-jdbcapi

sqlalchemy-jdbcapi

JSON →
library2.2.1pypypi✓ verified 82d ago

SQLAlchemy-JDBCAPI is a modern SQLAlchemy dialect that provides native DB-API 2.0 implementation for JDBC connections using JPype, and ODBC connections via pyodbc. It supports a wide range of databases including PostgreSQL, MySQL, SQL Server, Oracle, and many others, with features like automatic JDBC driver management. The current version is 2.2.1, and it maintains an active release cadence with frequent updates and new features such as full asyncio support.

pip install sqlalchemy-jdbcapi
INSTALL
IMPORT
SIG · SQLALCHEMY-JDBCAPI
S
sqlalchemy-jdbcapi
databasepythonv2.2.1
Install
3.3s avg
Import
Disk
43MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
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.
fix
Upgrade 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.
fix
Ensure 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.
fix
For 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.
fix
Upgrade `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.
Agent activity
58 hits · last 30 days
node
50
OpenAI (training)
1
Resources