Skip to main content

Use JDBC database drivers from Python 2/3 or Jython with a DB-API.

Project description,_2.7,_3.4-blue.svg

The JayDeBeApi module allows you to connect from Python code to databases using Java JDBC. It provides a Python DB-API v2.0 to that database.

It works on ordinary Python (cPython) using the JPype Java integration or on Jython to make use of the Java JDBC driver.

In contrast to zxJDBC from the Jython project JayDeBeApi let’s you access a database with Jython AND Python with only minor code modifications. JayDeBeApi’s future goal is to provide a unique and fast interface to different types of JDBC-Drivers through a flexible plug-in mechanism.


You can get and install JayDeBeApi with pip

$ pip install JayDeBeApi

If you want to install JayDeBeApi in Jython make sure to have pip or EasyInstall available for it.

Or you can get a copy of the source by cloning from the JayDeBeApi github project and install with

$ python install

or if you are using Jython use

$ jython install

It has been tested with Jython 2.7-rc1.

If you are using cPython ensure that you have installed JPype properly. It has been tested with JPype1 0.5.7. Older JPype installations may cause problems.


Basically you just import the jaydebeapi Python module and execute the connect method. This gives you a DB-API conform connection to the database.

The first argument to connect is the name of the Java driver class. Then you can supply a single argument or a sequence of arguments that are internally passed to the Java DriverManager.getConnection method. Usually this is the JDBC connection URL. See the Javadoc of DriverManager class for details.

The next parameter to connect is optional and specifies the jar-Files of the driver if your classpath isn’t set up sufficiently yet. The classpath set in CLASSPATH environment variable will be honored. See the documentation of your Java runtime environment.

Here is an example:

>>> import jaydebeapi
>>> conn = jaydebeapi.connect('org.hsqldb.jdbcDriver',
...                           ['jdbc:hsqldb:mem:.', 'SA', ''],
...                           '/path/to/hsqldb.jar',)
>>> curs = conn.cursor()
>>> curs.execute('create table CUSTOMER'
...                '("CUST_ID" INTEGER not null,'
...                ' "NAME" VARCHAR not null,'
...                ' primary key ("CUST_ID"))'
...             )
>>> curs.execute("insert into CUSTOMER values (1, 'John')")
>>> curs.execute("select * from CUSTOMER")
>>> curs.fetchall()
[(1, u'John')]

If you’re having trouble getting this work check if your JAVA_HOME environmentvariable is set correctly. For example I have to set it on my Ubuntu machine like this

$ JAVA_HOME=/usr/lib/jvm/java-6-openjdk python

Supported databases

In theory every database with a suitable JDBC driver should work. It is known to work with the following databases:

Database JDBC driver Supported Remarks
SQLite 3 SqliteJDBC v056 Good Can’t interpret selected BLOBs correctly.
  Sqlite Java Wrapper javasqlite-20110106-win32 Medium Weird type handling.
Hypersonic SQL (HSQLDB) Builtin Very Good No BLOB support by database.
Hypersonic SQL (HSQLDB) 2 Builtin Medium Weird decimal type conversions. No BLOB support.
IBM DB2 for z/OS JDBC type 4 drivers from IBM (db2jcc.jar) Medium. Not thoroughly tested but seems to work without problems.
Oracle 11g Oracle Thin Driver Medium Not thoroughly tests. No support for rading of timestamps yet.
Teradata DB terajdbc4.jar Medium A user reported success.
Other databases Other JDBC drivers Unkown Please test yourself and report the results.


Please submit bugs and patches. All contributors will be acknowledged. Thanks!


JayDeBeApi is released under the GNU Lesser General Public license (LGPL). See the file COPYING and COPYING.LESSER in the distribution for details.


  • Next version - unreleased
  • 0.2.0 - 2015-04-26
    • Python 3 support (requires JPype1 >= 0.6.0).
  • 0.1.6 - 2015-04-10
    • Fix Jython handling of Java exceptions that don’t subclass python Exception
    • Enrich exceptions with message from java SQLExceptions
    • Be more specific about DB API exceptions: Distinguish DatabaseError and InterfaceError.
    • Fix typo LONGNARCHAR vs LONGVARCHAR (thanks @datdo for reporting #4)
  • 0.1.5 - 2015-03-02
    • Add version number to module.
    • Improve robustness of java to python type conversion.
    • Support Time type.
    • Add DB-API compliant exception handling.
    • Minor documentation improvements.
    • Some development related changes (Host project at github, use Travis CI, use JPype1 for tests).
  • 0.1.4 - 2013-10-29
    • More convenient way to setup Java classpath. Important note check the changes to the connect method and adapt your code.
    • Honor CLASSPATH if used in JPype mode.
    • Set .rowcount properly.
    • Changed signature of .setoutputsize() to be DB-API compliant.
  • 0.1.3 - 2011-01-27
    • Fixed DB-API violation: Use curs.execute('foo ?', (bar, baz)) instead of curs.execute('foo ?', bar, baz).
    • Free resources after executemany call.
    • Improved type handling. Initial support for BLOB columns.
  • 0.1.2 - 2011-01-25
    • easy_install JayDeBeApi should really work.
  • 0.1.1 - 2010-12-12
    • Fixed bug #688290 “NULL values with converters error on fetch”.
    • Fixed bug #684909 “Selecting ROWIDs errors out on fetch”.
  • 0.1 - 2010-08-10
    • Initial release.

To do

  • Extract Java calls to separate Java methods to increase performance.
  • Check if can help making JayDeBeApi more DB-API compliant.
  • Test it on different databases and provide a flexible db specific pluign mechanism.
  • SQLAlchemy modules (separate project)

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for JayDeBeApi, version 0.2.0
Filename, size File type Python version Upload date Hashes
Filename, size JayDeBeApi-0.2.0-py2-none-any.whl (14.5 kB) File type Wheel Python version 2.7 Upload date Hashes View hashes
Filename, size JayDeBeApi-0.2.0-py3-none-any.whl (14.5 kB) File type Wheel Python version 3.4 Upload date Hashes View hashes
Filename, size JayDeBeApi-0.2.0.tar.gz (31.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page