SQLAlchemy JDBC/ODBC API

Modern, type-safe SQLAlchemy dialect for JDBC and ODBC connections with native Python implementation.

Community Help Needed: We don't have access to all database systems for thorough testing. If you encounter issues connecting to a particular database, please raise an issue - we rely on community feedback to improve support for all databases.

Features

• Automatic JDBC driver download from Maven Central (zero configuration!)
• ODBC support for native database connectivity
• Full SQLAlchemy integration (ORM, reflection, Alembic, Inspector API)
• DataFrame integration (pandas, polars, pyarrow)
• ️ 18 database dialects (PostgreSQL, Oracle, MySQL, MariaDB, SQL Server, DB2, SQLite, OceanBase, GBase 8s, IBM iSeries, MS Access, Apache Phoenix)
• Asyncio support for Core and ORM operations
• HikariCP connection pooling for high-performance connections
• Database X-Ray for query monitoring and performance tracing
• Modern Python 3.10+ with full type hints
• SQLAlchemy 2.0+ compatible

Installation

# Basic installation
pip install sqlalchemy-jdbcapi

# With DataFrame support
pip install sqlalchemy-jdbcapi[dataframe]

# With ODBC support
pip install sqlalchemy-jdbcapi[odbc]

JDBC Requirements

JDBC requires Java Runtime Environment (JRE) 8+:

# Check Java installation
java -version

# Install on Ubuntu/Debian
sudo apt-get install default-jre

# Install on macOS
brew install openjdk

Quick Start

JDBC (Recommended - Auto-Download)

from sqlalchemy import create_engine

# PostgreSQL - driver downloads automatically!
engine = create_engine('jdbcapi+postgresql://user:password@localhost/mydb')

# Oracle
engine = create_engine('jdbcapi+oracle://user:password@localhost:1521/ORCL')

# MySQL
engine = create_engine('jdbcapi+mysql://user:password@localhost/mydb')

ODBC (Alternative - No JVM)

from sqlalchemy import create_engine

# Requires OS-installed ODBC driver
engine = create_engine('odbcapi+postgresql://user:password@localhost/mydb')

Usage Example

from sqlalchemy import create_engine, text

engine = create_engine('jdbcapi+postgresql://user:pass@localhost/db')

with engine.connect() as conn:
    result = conn.execute(text("SELECT * FROM users"))
    for row in result:
        print(row)

Documentation

📖 Full Documentation (Recommended)

Quick Links

• Quick Start Guide - Get started in 5 minutes
• Usage Guide - Comprehensive examples
• Drivers Guide - Driver installation & configuration
• SQLAlchemy Integration - ORM, reflection, Alembic
• Examples - Code examples for all databases
• Troubleshooting - Common issues & solutions

Supported Databases

Database	JDBC	ODBC	Auto-Download	Async
PostgreSQL	✅	✅	✅	✅
Oracle	✅	✅	✅	✅
MySQL	✅	✅	✅	✅
MariaDB	✅	✅	✅	✅
SQL Server	✅	✅	✅	✅
DB2	✅	❌	✅	✅
SQLite	✅	❌	✅	✅
OceanBase	✅	❌	✅	❌
GBase 8s	✅	❌	✅	❌
IBM iSeries	✅	❌	✅	❌
MS Access	✅	❌	✅	❌
Apache Phoenix	✅	❌	✅	❌

See Drivers Guide for detailed configuration.

What's New in 2.1

Version 2.1 adds major new capabilities:

• New database dialects: GBase 8s, IBM iSeries, MS Access, Apache Phoenix/Avatica
• Asyncio support: Full async/await for Core and ORM operations
• HikariCP integration: High-performance connection pooling
• Database X-Ray: Query monitoring, metrics, and performance tracing
• Docker test suite: Functional tests with real databases

What's New in 2.0

Version 2.0 was a complete modernization:

• Native JDBC implementation (replaced JayDeBeApi)
• Added ODBC support
• DataFrame integration (pandas, polars, pyarrow)
• Full SQLAlchemy native dialect (ORM, reflection, Alembic)
• Expanded from 3 to 12 database dialects
• Modern Python 3.10+ with complete type hints
• SQLAlchemy 2.0+ support

See CHANGELOG.md for migration guide.

Contributing

We welcome contributions! Please see:

• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Community guidelines
• SECURITY.md - Security policy

Development

# Clone repository
git clone https://github.com/daneshpatel/sqlalchemy-jdbcapi.git
cd sqlalchemy-jdbcapi

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run linting
ruff check src tests

See Contributing Guide for detailed instructions.

License

This project is licensed under the Apache License 2.0 - see LICENSE file for details.

Links

• Documentation - Full documentation
• PyPI - Package on PyPI
• GitHub - Source code
• Issues - Bug reports & feature requests
• Changelog - Version history

Support

• Issues: Report bugs or request features on GitHub Issues
• Discussions: Ask questions on GitHub Discussions