JDBC Module

The JDBC module provides a native DB-API 2.0 compliant implementation for JDBC connectivity using JPype.

Connection

class sqlalchemy_jdbcapi.jdbc.connection.Connection(jclassname, url, driver_args=None, jars=None, libs=None)

Bases: object

DB-API 2.0 compliant connection to a JDBC database.

This class wraps a JDBC Connection object from JPype.

__init__(jclassname, url, driver_args=None, jars=None, libs=None)

Create a JDBC connection.

Parameters:

• jclassname (str) – Fully qualified Java class name of JDBC driver

• url (str) – JDBC connection URL

• driver_args (dict[str, Any] | list[Any] | None) – Connection properties (dict) or [user, password] (list)

• jars (list[str] | None) – List of JAR file paths (for classpath)

• libs (list[str] | None) – Additional native library paths

Raises:

• InterfaceError – If JVM or driver cannot be loaded

• DatabaseError – If connection fails

close()

Close the connection.

commit()

Commit current transaction.

rollback()

Rollback current transaction.

cursor()

Create a new cursor.

Returns:

Cursor object

Raises:

InterfaceError – If connection is closed

Return type:

Cursor

set_auto_commit(auto_commit)

Set auto-commit mode.

Parameters:

auto_commit (bool) – True to enable auto-commit, False to disable

get_auto_commit()

Get current auto-commit mode.

property closed: bool

Check if connection is closed.

__enter__()

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

__del__()

Destructor to ensure connection is closed.

Cursor

class sqlalchemy_jdbcapi.jdbc.cursor.Cursor(connection, jdbc_connection)

Bases: object

DB-API 2.0 compliant cursor for JDBC connections.

This class wraps a JDBC Statement/PreparedStatement and ResultSet.

__init__(connection, jdbc_connection)

Initialize cursor.

Parameters:

• connection (Any) – Parent Connection object

• jdbc_connection (Any) – JDBC Connection object from JPype

property description: tuple[tuple[str, Any, None, None, None, None, None], ...] | None

Get column descriptions from last query.

Returns 7-item tuples: (name, type_code, display_size, internal_size, precision, scale, null_ok). We only provide name and type_code.

property rowcount: int

Get number of rows affected by last operation.

property arraysize: int

Get default number of rows to fetch.

close()

Close the cursor.

execute(operation, parameters=None)

Execute a database operation.

Parameters:

• operation (str) – SQL query or command

• parameters (Sequence[Any] | None) – Parameters for the query

Returns:

Self for chaining

Raises:

ProgrammingError – If cursor is closed or operation fails

Return type:

Cursor

executemany(operation, seq_of_parameters)

Execute a database operation multiple times.

Parameters:

• operation (str) – SQL query or command

• seq_of_parameters (Sequence[Sequence[Any]]) – Sequence of parameter sequences

Raises:

ProgrammingError – If operation fails

fetchone()

Fetch next row from query result.

Returns:

Tuple of column values or None if no more rows

Raises:

InterfaceError – If no query has been executed

Return type:

tuple[Any, …] | None

fetchmany(size=None)

Fetch multiple rows from query result.

Parameters:

size (int | None) – Number of rows to fetch (default: arraysize)

Returns:

List of row tuples

Raises:

InterfaceError – If no query has been executed

Return type:

list[tuple[Any, …]]

fetchall()

Fetch all remaining rows from query result.

Returns:

List of row tuples

Raises:

InterfaceError – If no query has been executed

Return type:

list[tuple[Any, …]]

setinputsizes(sizes)

Does nothing, for DB-API 2.0 compliance.

setoutputsize(size, column=None)

Does nothing, for DB-API 2.0 compliance.

__enter__()

Context manager entry.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

__iter__()

Make cursor iterable.

__next__()

Fetch next row for iteration.

to_arrow()

to_dict()

to_pandas()

to_polars()

Driver Manager

JDBC driver auto-download and management.

This module handles automatic downloading of JDBC drivers from Maven Central and provides fallback to manual driver configuration via CLASSPATH.

class sqlalchemy_jdbcapi.jdbc.driver_manager.JDBCDriver(group_id, artifact_id, version, classifier=None)

Bases: NamedTuple

JDBC driver metadata for automatic download.

group_id: str

Alias for field number 0

artifact_id: str

Alias for field number 1

version: str

Alias for field number 2

classifier: str | None

Alias for field number 3

property filename: str

Get the JAR filename.

property maven_url: str

Get the Maven Central download URL.

sqlalchemy_jdbcapi.jdbc.driver_manager.get_driver_cache_dir()

Get the driver cache directory.

Returns:

Path to the driver cache directory.

Return type:

Path

sqlalchemy_jdbcapi.jdbc.driver_manager.download_driver(driver, cache_dir=None, force=False)

Download a JDBC driver from Maven Central.

Parameters:

• driver (JDBCDriver) – JDBC driver metadata.

• cache_dir (Path | None) – Directory to cache downloaded drivers. If None, uses default.

• force (bool) – Force re-download even if driver exists.

Returns:

Path to the downloaded driver JAR file.

Raises:

RuntimeError – If download fails.

Return type:

Path

sqlalchemy_jdbcapi.jdbc.driver_manager.get_driver_path(database, driver=None, auto_download=True, cache_dir=None)

Get the path to a JDBC driver, downloading if necessary.

Parameters:

• database (str) – Database name (e.g., ‘postgresql’, ‘mysql’).

• driver (JDBCDriver | None) – Custom driver metadata. If None, uses recommended driver.

• auto_download (bool) – Whether to auto-download driver if not found.

• cache_dir (Path | None) – Directory to cache downloaded drivers.

Returns:

Path to the JDBC driver JAR file.

Raises:

RuntimeError – If driver not found and auto-download disabled.

Return type:

Path

sqlalchemy_jdbcapi.jdbc.driver_manager.get_all_driver_paths(databases=None, auto_download=True, cache_dir=None)

Get paths to multiple JDBC drivers.

Parameters:

• databases (list[str] | None) – List of database names. If None, downloads all recommended drivers.

• auto_download (bool) – Whether to auto-download drivers if not found.

• cache_dir (Path | None) – Directory to cache downloaded drivers.

Returns:

List of paths to JDBC driver JAR files.

Return type:

list[Path]

sqlalchemy_jdbcapi.jdbc.driver_manager.get_classpath_with_drivers(databases=None, auto_download=True, manual_classpath=None)

Get comprehensive classpath including auto-downloaded and manual drivers.

Parameters:

• databases (list[str] | None) – List of database names for auto-download. If None, downloads all recommended.

• auto_download (bool) – Whether to auto-download drivers.

• manual_classpath (list[Path] | None) – Additional manual classpath entries.

Returns:

List of all classpath entries.

Return type:

list[Path]

sqlalchemy_jdbcapi.jdbc.driver_manager.verify_driver(driver_path)

Verify that a JDBC driver JAR file is valid.

Parameters:

driver_path (Path) – Path to the driver JAR file.

Returns:

True if driver appears valid, False otherwise.

Return type:

bool

sqlalchemy_jdbcapi.jdbc.driver_manager.list_cached_drivers(cache_dir=None)

List all cached JDBC drivers.

Parameters:

cache_dir (Path | None) – Directory to check. If None, uses default.

Returns:

List of paths to cached driver JAR files.

Return type:

list[Path]

sqlalchemy_jdbcapi.jdbc.driver_manager.clear_driver_cache(cache_dir=None)

Clear the driver cache directory.

Parameters:

cache_dir (Path | None) – Directory to clear. If None, uses default.

Returns:

Number of files deleted.

Return type:

int

JVM Management

JVM management and initialization.

sqlalchemy_jdbcapi.jdbc.jvm.get_classpath(auto_download=True, databases=None)

Get JDBC driver classpath from environment, auto-download, or both.

Parameters:

• auto_download (bool) – Whether to auto-download recommended JDBC drivers.

• databases (list[str] | None) – List of database names for auto-download (e.g., [‘postgresql’, ‘mysql’]). If None and auto_download is True, downloads all recommended drivers.

Returns:

List of paths to JDBC driver JAR files.

Return type:

list[Path]

sqlalchemy_jdbcapi.jdbc.jvm.start_jvm(classpath=None, jvm_path=None, jvm_args=None, auto_download=True, databases=None)

Start the JVM with specified classpath and arguments.

Parameters:

• classpath (list[Path] | None) – List of paths to add to classpath. If None, uses environment + auto-download.

• jvm_path (Path | None) – Path to JVM library. If None, JPype will auto-detect.

• jvm_args (list[str] | None) – Additional JVM arguments (e.g., [‘-Xmx512m’]).

• auto_download (bool) – Whether to auto-download JDBC drivers. Default: True.

• databases (list[str] | None) – List of database names for auto-download. If None, downloads common drivers.

Raises:

JVMNotStartedError – If JVM fails to start.

sqlalchemy_jdbcapi.jdbc.jvm.is_jvm_started()

Check if JVM is started.

sqlalchemy_jdbcapi.jdbc.jvm.shutdown_jvm()

Shutdown the JVM (optional, usually not needed).

sqlalchemy_jdbcapi.jdbc.jvm.get_java_class(class_name)

Get a Java class by name.

Parameters:

class_name (str) – Fully qualified Java class name.

Returns:

Java class object.

Raises:

JVMNotStartedError – If JVM is not started.

Return type:

Any

Type Converter

Type conversion between JDBC and Python types.

class sqlalchemy_jdbcapi.jdbc.type_converter.TypeConverter

Bases: object

Handles conversion between JDBC SQL types and Python types.

Java SQL Types (from java.sql.Types): -7 BIT -6 TINYINT -5 BIGINT -4 LONGVARBINARY -3 VARBINARY -2 BINARY -1 LONGVARCHAR 1 CHAR 2 NUMERIC 3 DECIMAL 4 INTEGER 5 SMALLINT 6 FLOAT 7 REAL 8 DOUBLE 12 VARCHAR 91 DATE 92 TIME 93 TIMESTAMP 2004 BLOB 2005 CLOB 2011 NCLOB

JDBC_TYPES = {-7: 'BIT', -6: 'TINYINT', -5: 'BIGINT', -4: 'LONGVARBINARY', -3: 'VARBINARY', -2: 'BINARY', -1: 'LONGVARCHAR', 1: 'CHAR', 2: 'NUMERIC', 3: 'DECIMAL', 4: 'INTEGER', 5: 'SMALLINT', 6: 'FLOAT', 7: 'REAL', 8: 'DOUBLE', 12: 'VARCHAR', 91: 'DATE', 92: 'TIME', 93: 'TIMESTAMP', 2004: 'BLOB', 2005: 'CLOB', 2011: 'NCLOB'}

convert_from_jdbc(resultset, column_index, sql_type)

Convert JDBC result to Python type.

Parameters:

• resultset (Any) – JDBC ResultSet object

• column_index (int) – 1-based column index

• sql_type (int) – JDBC SQL type code

Returns:

Python value

Return type:

Any

DataFrame Integration

DataFrame integration for pandas, polars, and Apache Arrow.

This module provides utilities to convert JDBC query results directly into DataFrames for data science and ML workflows.

sqlalchemy_jdbcapi.jdbc.dataframe.cursor_to_pandas(cursor)

Convert cursor results to pandas DataFrame.

Parameters:

cursor (Cursor) – Cursor with executed query

Returns:

pandas.DataFrame

Raises:

• ImportError – If pandas is not installed

• ValueError – If cursor has no results

Return type:

Any

Example

>>> cursor.execute("SELECT * FROM users")
>>> df = cursor_to_pandas(cursor)
>>> print(df.head())

sqlalchemy_jdbcapi.jdbc.dataframe.cursor_to_polars(cursor)

Convert cursor results to polars DataFrame.

Parameters:

cursor (Cursor) – Cursor with executed query

Returns:

polars.DataFrame

Raises:

• ImportError – If polars is not installed

• ValueError – If cursor has no results

Return type:

Any

Example

>>> cursor.execute("SELECT * FROM users")
>>> df = cursor_to_polars(cursor)
>>> print(df.head())

sqlalchemy_jdbcapi.jdbc.dataframe.cursor_to_arrow(cursor)

Convert cursor results to Apache Arrow Table.

Parameters:

cursor (Cursor) – Cursor with executed query

Returns:

pyarrow.Table

Raises:

• ImportError – If pyarrow is not installed

• ValueError – If cursor has no results

Return type:

Any

Example

>>> cursor.execute("SELECT * FROM users")
>>> table = cursor_to_arrow(cursor)
>>> print(table.schema)

sqlalchemy_jdbcapi.jdbc.dataframe.cursor_to_dict(cursor)

Convert cursor results to list of dictionaries.

Parameters:

cursor (Cursor) – Cursor with executed query

Returns:

List of row dictionaries

Return type:

list[dict[str, Any]]

Example

>>> cursor.execute("SELECT * FROM users")
>>> rows = cursor_to_dict(cursor)
>>> print(rows[0])
{'id': 1, 'name': 'Alice', 'email': 'alice@example.com'}

Exceptions

JDBC Exception hierarchy following DB-API 2.0 specification.

exception sqlalchemy_jdbcapi.jdbc.exceptions.Error

Bases: Exception

Base class for all JDBC-related errors.

exception sqlalchemy_jdbcapi.jdbc.exceptions.Warning

Bases: Exception

Exception raised for important warnings.

exception sqlalchemy_jdbcapi.jdbc.exceptions.InterfaceError

Bases: Error

Exception raised for errors related to the database interface.

exception sqlalchemy_jdbcapi.jdbc.exceptions.DatabaseError

Bases: Error

Exception raised for errors related to the database.

exception sqlalchemy_jdbcapi.jdbc.exceptions.InternalError

Bases: DatabaseError

Exception raised when the database encounters an internal error.

exception sqlalchemy_jdbcapi.jdbc.exceptions.OperationalError

Bases: DatabaseError

Exception raised for operational database errors.

exception sqlalchemy_jdbcapi.jdbc.exceptions.ProgrammingError

Bases: DatabaseError

Exception raised for programming errors.

exception sqlalchemy_jdbcapi.jdbc.exceptions.IntegrityError

Bases: DatabaseError

Exception raised when database integrity is violated.

exception sqlalchemy_jdbcapi.jdbc.exceptions.DataError

Bases: DatabaseError

Exception raised for errors related to processed data.

exception sqlalchemy_jdbcapi.jdbc.exceptions.NotSupportedError

Bases: DatabaseError

Exception raised when a method or database API is not supported.

exception sqlalchemy_jdbcapi.jdbc.exceptions.JDBCDriverNotFoundError

Bases: InterfaceError

Exception raised when JDBC driver cannot be found.

exception sqlalchemy_jdbcapi.jdbc.exceptions.JVMNotStartedError

Bases: InterfaceError

Exception raised when JVM is not started.

DB-API Type Objects

DB-API 2.0 type objects and constructors.

class sqlalchemy_jdbcapi.jdbc.types.DBAPITypeObject(*values)

Bases: object

Base class for DB-API type objects.

__init__(*values)

sqlalchemy_jdbcapi.jdbc.types.Date(year, month, day)

Construct a date object.

sqlalchemy_jdbcapi.jdbc.types.Time(hour, minute, second)

Construct a time object.

sqlalchemy_jdbcapi.jdbc.types.Timestamp(year, month, day, hour, minute, second)

Construct a timestamp object.

sqlalchemy_jdbcapi.jdbc.types.DateFromTicks(ticks)

Construct a date object from ticks since epoch.

sqlalchemy_jdbcapi.jdbc.types.TimeFromTicks(ticks)

Construct a time object from ticks since epoch.

sqlalchemy_jdbcapi.jdbc.types.TimestampFromTicks(ticks)

Construct a timestamp object from ticks since epoch.

sqlalchemy_jdbcapi.jdbc.types.Binary(value)

Construct a binary object.