# Supported Databases

## Overview

The following appendix covers the database and JDBC driver versions that are known to work with OpenJPA, along with any database specific configuration parameters, known issues or limitations. The Verified Database Matrix, contains the list of databases and drivers that were tested extensively against this release of OpenJPA, while the Compatible Database Matrix contains the list of databases and drivers that were tested against prior releases or by OpenJPA users and may not support every feature of this release. The Unverified Database Matrix contains a list of databases which have been reported to work, but have not been tested by the development team.

## Verified Database Matrix

Following is a table of the supported database and JDBC driver versions that have been verified against this version of OpenJPA. For the list of other databases and drivers that were tested in prior releases or by other OpenJPA users, but may not support every feature of this release, please refer to the Compatible Database Matrix section.

Supported Databases and JDBC Drivers

Database Name | Database Version | JDBC Driver Name | JDBC Driver Version
--- | --- | --- | ---
Apache Derby | 10.2.2.0, 10.3.3.0, 10.4.2.0, 10.5.3.0, 10.8.2.2 | Apache Derby Embedded JDBC Driver | Same as Database Version
IBM DB2 | 8.1, 8.2, 9.1, 9.5, 9.7 | IBM DB2 JDBC Universal Driver | 3.50.152
IBM Informix Dynamic Server | 10.00xC6, 11.10xC1, 11.5xC1 | Informix JDBC driver | 3.00 JC3, 3.10 JC1, 3.50 JC1
Microsoft SQL Server | 2005 (9.00), 2008 (10.00) | Microsoft SQL Server JDBC Driver | 1.2 or 2.0
MySQL | 5.0.26, 5.1.6 | MySQL Driver | 5.1.6
Oracle | 10g (10.1, 10.2), 11g (11.1, 11.2) | Oracle JDBC driver | 11.2.0.1
PostgreSQL | 8.3.5, 8.4 | PostgreSQL Native Driver | 8.3 JDBC3 (build 603), 8.4 JDBC3 (build 701)
IBM solidDB | 6.5.0.0 | solidDB JDBC Driver | 2.0
Sybase Adaptive Server Enterprise | 12.5, 15.0 | jConnect | 5.5, 6.0

## Compatible Database Matrix

Following is a table of the database and JDBC driver versions that are compatible with OpenJPA. Some of these databases have been tested against this version of OpenJPA, while others were added or tested in prior releases and may not support all of the new features of this release. For the list of databases that have been fully tested against this release, please refer to the Verified Database Matrix section.

Compatible Databases and JDBC Drivers

Database Name | Database Version | JDBC Driver Name | JDBC Driver Version
--- | --- | --- | ---
Apache Derby | 10.1.2.1 | Apache Derby Embedded JDBC Driver | 10.1.2.1
Borland Interbase | 7.1.0.202 | Interclient | 4.5.1
Borland JDataStore | 6.0 | Borland JDataStore | 6.0
DB2 | 8.1 | IBM DB2 JDBC Universal Driver | 1.0.581, 2.10.72
Empress | 8.62 | Empress Category 2 JDBC Driver | 8.62
Firebird | 1.5, 2.0, 2.1 | JayBird JCA/JDBC driver | 2.1.6
H2 Database Engine | 1.1.118 | H2 | Same as Database Version
Hypersonic Database Engine | 1.8.0, 2.0.1 RC2 | Hypersonic | Same as Database Version
Informix Dynamic Server | 9.30.UC10, 9.4xC7 | Informix JDBC driver | 2.21.JC2, 3.00 JC3, 3.10 JC1
Ingres Database | 9.2 | Ingres JDBC Driver | 9.2-3.4.8
InterSystems Cache | 5.0 | Cache JDBC Driver | 5.0
Microsoft Access | 9.0 (a.k.a. "2000") | DataDirect SequeLink | 5.4.0038
Microsoft SQL Server | 2000 (8.00) | Microsoft SQL Server JDBC Driver | 1.2
Microsoft Visual FoxPro | 7.0 | DataDirect SequeLink | 5.4.0038
MySQL | 3.23.43-log | MySQL Driver | 3.0.14
Oracle | 8.1, 9.2 | Oracle JDBC driver | 10.2.0.1
Pointbase | 4.4 | Pointbase JDBC driver | 4.4 (4.4)
PostgreSQL | 7.2.1, 8.1.5 | PostgreSQL Native Driver | 8.1
IBM solidDB | 6.5.0.0 | solidDB JDBC Driver | 2.0
Sybase Adaptive Server Enterprise | 12.5 | jConnect | 5.5 (5.5)

## Unverified Database Matrix

Following is a table of the database and JDBC driver versions that have been reported to work with OpenJPA by the community but have not been verified by the development team. In some cases this is a question of availability since the developers may not be able to obtain a license to test, or have experience configuring these databases. For the list of databases that have been fully tested against this release, please refer to the Verified Database Matrix section.

Unverified Databases and JDBC Drivers

Database Name | Database Version | JDBC Driver Name | JDBC Driver Version
--- | --- | --- | ---
SAP MaxDB |  |  |

## Apache Derby

Example properties for Derby

    openjpa.ConnectionDriverName: org.apache.derby.jdbc.EmbeddedDriver
    openjpa.ConnectionURL: jdbc:derby:DB_NAME;create=true

## Borland Interbase

Example properties for Interbase

    openjpa.ConnectionDriverName: interbase.interclient.Driver
    openjpa.ConnectionURL: jdbc:interbase://SERVER_NAME:SERVER_PORT/DB_PATH

### Known issues with Interbase

- Interbase does not support record locking, so datastore transactions cannot use the pessimistic lock manager.

- Interbase does not support the `LOWER`, `SUBSTRING`, or `INSTR` SQL functions.

## JDataStore

Example properties for JDataStore

    openjpa.ConnectionDriverName: com.borland.datastore.jdbc.DataStoreDriver
    openjpa.ConnectionURL: jdbc:borland:dslocal:db-jdatastore.jds;create=true

## IBM DB2

Example properties for IBM DB2

    openjpa.ConnectionDriverName: com.ibm.db2.jcc.DB2Driver
    openjpa.ConnectionURL: jdbc:db2://SERVER_NAME:SERVER_PORT/DB_NAME

### Known issues with DB2

- Floats and doubles may lose precision when stored.

- Empty char values are stored as NULL.

- Fields of type BLOB and CLOB are limited to 1M. This number can be increased by extending DB2Dictionary.

- Explicit creation of indexes specified by the OpenJPA @Index annotation will fail on DB2 for iSeries if the default schema used by the JDBC driver does not exist. If a default schema is not specified on the connection, the iSeries will default to the user profile name. If a schema of that name does not exist, DB2 on iSeries will not create the schema, resulting in a failure when creating the index. The failure message will look similar to: "[SQL0204] USERNAME in QSYS type *LIB not found." To work around this issue, specify a default schema on the JDBC URL or data source property and make sure that schema exists or create a schema which matches the user profile of the connection.

- Use of DB2 on z/OS with the IBM JCC driver requires the DESCSTAT subsystem parameter value to be set to 'YES'. If this parameter is set to 'NO', the mapping tool will fail with a persistence exception containing this text: "Invalid parameter: Unknown column name TABLE_SCHEM". After changing the value of DESCSTAT, DB2 metadata tables must be recreated by running the DSNTIJMS job. See DB2 for z/OS documentation for additional information.

- When using LOBs with persistent attributes of a streaming data type (e.g. `java.io.InputStream`) in the case of very large LOB, DB2 JCC driver will automatically use progressive streaming to retrieve the LOB data. With progressiveStreaming, the inputStream retrieved must be fully materialized before the next iteration of call to rs.next(). By default this will result in a LobClosedException when OpenJPA processes the InputStream.

  To work around this condition you may force fullyMaterializedLobData to true in the connection URL as shown below :

      openjpa.ConnectionURL: jdbc:db2://localhost:50000/demodb:fullyMaterializeLobData=true;progressiveStreaming=NO

## Empress

Example properties for Empress

    openjpa.ConnectionDriverName: empress.jdbc.empressDriver
    openjpa.ConnectionURL: jdbc:empress://SERVER=yourserver;PORT=6322;DATABASE=yourdb

### Known issues with Empress

- Empress enforces pessimistic semantics (lock on read) when not using `AllowConcurrentRead` property (which bypasses row locking) for EmpressDictionary.

- Only the category 2 non-local driver is supported.

## H2 Database Engine

Example properties for H2 Database Engine

    openjpa.ConnectionDriverName: org.h2.Driver
    openjpa.ConnectionURL: jdbc:h2:DB_NAME

### Known issues with H2 Database Engine

- None

## Hypersonic

Example properties for Hypersonic

    openjpa.ConnectionDriverName: org.hsqldb.jdbcDriver
    openjpa.ConnectionURL: jdbc:hsqldb:DB_NAME

### Known issues with Hypersonic

- Hypersonic does not support pessimistic locking, so non-optimistic transactions will fail unless the `SimulateLocking` property is set for the openjpa.jdbc.DBDictionary

## Firebird

Example properties for Firebird

    openjpa.ConnectionDriverName: org.firebirdsql.jdbc.FBDriver
    openjpa.ConnectionURL: jdbc:firebirdsql:SERVER_NAME/3050:DB_PATH_OR_ALIAS

### Known issues with Firebird

- Firebird does not support auto-increment columns.

- In order to use many of JPQL functions with Firebird 1.5, Interbase UDFs have to be available in the database.

## Informix

Example properties for Informix Dynamic Server

    openjpa.ConnectionDriverName: com.informix.jdbc.IfxDriver
    openjpa.ConnectionURL: \
      jdbc:informix-sqli://SERVER_NAME:SERVER_PORT/DB_NAME:INFORMIXSERVER=SERVER_ID

### Known issues with Informix

- None

## Ingres Database

Example properties for Ingres

    openjpa.ConnectionDriverName: com.ingres.jdbc.IngresDriver
    openjpa.ConnectionURL: \
        jdbc:ingres://SERVER_NAME:DAS_SERVER_PORT/DB_NAME

### Known issues with Ingres

- Databases must be created with the -n flag for Unicode compatibility in order to use LOBs.

## InterSystems Cache

Example properties for InterSystems Cache

    openjpa.ConnectionDriverName: com.intersys.jdbc.CacheDriver
    openjpa.ConnectionURL: jdbc:Cache://SERVER_NAME:SERVER_PORT/DB_NAME

### Known issues with InterSystems Cache

- Support for Cache is done via SQL access over JDBC, not through their object database APIs.

## Microsoft Access

Example properties for Microsoft Access

    openjpa.ConnectionDriverName: com.ddtek.jdbc.sequelink.SequeLinkDriver
    openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT

### Known issues with Microsoft Access

- Using the Sun JDBC-ODBC bridge to connect is not supported.

## Microsoft SQL Server

Example properties for Microsoft SQL Server

    openjpa.ConnectionDriverName: com.microsoft.sqlserver.jdbc.SQLServerDriver
    openjpa.ConnectionURL: \
        jdbc:sqlserver://SERVER_NAME:1433;DatabaseName=DB_NAME;selectMethod=cursor;sendStringParametersAsUnicode=false

### Known issues with SQL Server

- When using a Microsoft SQL Server JDBC Driver v1.2 or earlier, the ConnectionURL must always contain the `selectMethod=cursor` string, which is necessary for the driver to properly support large result sets.

- When using a Microsoft SQL Server JDBC Driver v1.2 or earlier, the JDBC driver has bugs that manifest themselves when prepared statements are pooled. Please disable prepared statement pooling by including the `MaxCachedStatements=0` configuration property in your org.apache.openjpa.ConnectionFactoryProperties.

- SQL Server date fields are accurate only to the nearest 3 milliseconds, possibly resulting in precision loss in stored dates.

- Adding `sendStringParametersAsUnicode=false` to the ConnectionURL may significantly increase performance.

- The Microsoft SQL Server driver only emulates batch updates. The DataDirect JDBC driver has true support for batch updates, and may result in a significant performance gain.

- Floats and doubles may lose precision when stored.

- `TEXT` columns cannot be used in queries.

- When using a SQL Server instance that has been configured to be case-sensitive in schema names, you need to set the "schemaCase=preserve" parameter in the openjpa.jdbc.DBDictionary property.

- SQL Server 2005 does not support native sequences. If you would like to use generated values with SQL Server you should use GenerationType.IDENTITY, GenerationType.TABLE, or GenerationType.AUTO.

- The use of LOB streaming is limited. When reading LOB data from the database, the Microsoft SQL Server driver will actually load all the data into memory at the same time.

- The SQL Server 2008 DATETIME2 data type supports 7 digits sub-second precision. When DataDirect JDBC driver is used with SQL Server 2008, setTimestamp method call with a java.sql.Timestamp argument of more than 3 digits precision in a prepared statement will result in truncation. This may cause loss of data precision or optimistic lock exception if an entity uses Timestamp type as version field.

## Microsoft FoxPro

Example properties for Microsoft FoxPro

    openjpa.ConnectionDriverName: com.ddtek.jdbc.sequelink.SequeLinkDriver
    openjpa.ConnectionURL: jdbc:sequelink://SERVER_NAME:SERVER_PORT

### Known issues with Microsoft FoxPro

- Using the Sun JDBC-ODBC bridge to connect is not supported.

## MySQL

Example properties for MySQL

    openjpa.ConnectionDriverName: com.mysql.jdbc.Driver
    openjpa.ConnectionURL: jdbc:mysql://SERVER_NAME/DB_NAME

### Using Query Hints with MySQL

MySQL has support for "query hints", which are keywords embedded in SQL that provide some hint for how the query should be executed. These hints are usually designed to provide suggestions to the MySQL query optimizer for how to efficiently perform a certain query, and aren't typically needed for any but the most intensive queries. OpenJPA supports hints to be placed between SELECT keyword and column list.

Using MySQL Hints

    Query query = em.createQuery(...);
    query.setHint("openjpa.hint.MySQLSelectHint", "SQL_NO_CACHE");
    List results = query.getResultList();

### Known issues with MySQL

- The default table types that MySQL uses do not support transactions, which will prevent OpenJPA from being able to roll back transactions. Use the `InnoDB` table type for any tables that OpenJPA will access.

- MySQL does not support sub-selects in versions prior to 4.1, so some operations (such as the `isEmpty()` method in a query) will fail due to this.

- Rollback due to database error or optimistic lock violation is not supported unless the table type is one of the MySQL transactional types. Explicit calls to `rollback()` before a transaction has been committed, however, are always supported.

- Floats and doubles may lose precision when stored in some datastores.

- When storing a field of type java.math.BigDecimal, some datastores will add extraneous trailing 0 characters, causing an equality mismatch between the field that is stored and the field that is retrieved.

- When using large result sets with MySQL there are a number of documented limitations. Please read the section titled "ResultSet" in the "MySQL JDBC API Implementation Notes". The net effect of these limitations is that you will have to read all of the rows of a result set (or close the connection) before you can issue any other queries on the connection, or an exception will be thrown. Setting openjpa.FetchBatchSize to any value greater than zero will enable streaming result sets.

- The use of LOB streaming is limited. When reading LOB data from the database, the MySQL JDBC driver will actually load all the data into memory at the same time.

## Oracle

Example properties for Oracle

    openjpa.ConnectionDriverName: oracle.jdbc.driver.OracleDriver
    openjpa.ConnectionURL: jdbc:oracle:thin:@SERVER_NAME:1521:DB_NAME

### Using Query Hints with Oracle

Oracle has support for "query hints", which are formatted comments embedded in SQL that provide some hint for how the query should be executed. These hints are usually designed to provide suggestions to the Oracle query optimizer for how to efficiently perform a certain query, and aren't typically needed for any but the most intensive queries.

Using Oracle Hints

    Query query = em.createQuery(...);
    query.setHint("openjpa.hint.OracleSelectHint", "/*+ first_rows(100) */");
    List results = query.getResultList();

### Known issues with Oracle

- The Oracle JDBC driver has significant differences between different versions. It is important to use the officially supported version of the drivers (10.2.0.1.0/11.2.0.x.0), which is backward compatible with previous versions of the Oracle server. It can be downloaded from http://www.oracle.com/technetwork/database/features/jdbc/index-091264.html.

- Empty string/char values are stored as NULL.

- Oracle corp's JDBC driver for Oracle has only limited support for batch updates. The result for OpenJPA is that batching of some statements may fail and in some cases, the exact object that failed an optimistic lock check cannot be determined. OpenJPA will throw an OptimisticException with more failed objects than actually failed. This situation may be resolved by disabling statement batching by setting the batchLimit value to zero or by using a more recent Oracle JDBC Driver (11.2.0.1) with batch support improvements. Attempting to resolve the issue with a more current driver is recommended since disabling statement batching can result in a decrease in performance.

  Property to disable statement batching for Oracle

      openjpa.jdbc.DBDictionary: oracle(batchLimit=0)

- Oracle cannot store numbers with more than 38 digits in numeric columns.

- Floats and doubles may lose precision when stored.

- CLOB columns cannot be used in queries.

- The use of LOBs with persistent attributes of a streaming data type (ex. `java.io.InputStream` or `java.io.Reader`) may require the same connection to be used over the life of the transaction or entity manager. If the same connection is not used for persistent operations a `java.io.IOException` with message `Closed Connection` may result. The OpenJPA property `openjpa.ConnectionRetainMode` can be used to control how OpenJPA uses datastore connections. See for details.

  Property to retain connection over the lifetime of the entity manager

      openjpa.ConnectionRetainMode: always

- Mapping persistent attributes to XML columns requires a JDBC 4 compliant driver if XML strings are longer than 4000 bytes, as counted in database. Otherwise an `ORA-01461: can bind a LONG value only for insert into a LONG column` error may result.

- If Oracle dictionary property `MaxEmbeddedBlobSize` or `MaxEmbeddedClobSize` is set to some limit (i.e. not -1) and embedded collection with BLOB/CLOB attribute is used, a `"org.apache.openjpa.persistence.ArgumentException: "x.y.z.EmbedOwner.embedCollection<element:class x.y.z.EmbedValue>" is mapped as embedded, but embedded field "x.y.z.EmbedOwner.embedCollection.x.y.z.EmbedValue.blob" is not embeddable. Embedded element/key/value types are limited to simple fields and direct relations to other persistent types"` error may result. To overcome this limitation, either use JDBC driver 11.2.0.x.0 (or later version) or set both `MaxEmbeddedBlobSize` and `MaxEmbeddedClobSize` properties to -1.

## Pointbase

Example properties for Pointbase

    openjpa.ConnectionDriverName: com.pointbase.jdbc.jdbcUniversalDriver
    openjpa.ConnectionURL: \
        jdbc:pointbase:DB_NAME,database.home=pointbasedb,create=true,cache.size=10000,database.pagesize=30720

### Known issues with Pointbase

- Fields of type BLOB and CLOB are limited to 1M. Set the `BlobTypeName` and/or `ClobTypeName` properties of the `openjpa.jdbc.DBDictionary` setting to override.

## PostgreSQL

Example properties for PostgreSQL

    openjpa.ConnectionDriverName: org.postgresql.Driver
    openjpa.ConnectionURL: jdbc:postgresql://SERVER_NAME:5432/DB_NAME

### Known issues with PostgreSQL

- Floats and doubles may lose precision when stored.

- PostgreSQL cannot store very low and very high dates.

- Empty string/char values are stored as NULL.

- Persistent fields of type java.io.Reader are not supported when using LOB streaming.

## IBM solidDB

Example properties for IBM solidDB

    openjpa.ConnectionDriverName: solid.jdbc.SolidDriver
    openjpa.ConnectionURL: jdbc:solid://localhost:2315/dba/dba

### M-type tables vs. D-type tables

IBM solidDB supports two types of tables: in-memory tables (M-tables) and on-disk tables (D-tables). Since cursor hold over commit can not apply to M-tables (which will cause SOLID Table Error 13187: The cursor cannot continue accessing M-tables after the transaction has committed or aborted. The statement must be re-executed), the default OpenJPA tables are D-tables. One can set the whole server to disk-based mode by adding [General] DefaultStoreIsMemory=no in solid.ini. The table types can also be determined by setting OpenJPA property "openjpa.jdbc.DBDictionary" with value "storeIsMemory=true" or "storeIsMemory=false" in the persistence.xml. The "STORE MEMORY" and "STORE DISK" will be appended to the create table DDL, respectively.

### Concurrency control mechanism

The default concurrency control mechanism depends on the table type: Disk-based tables (D-tables) are by default optimistic. Main-memory tables (M-tables) are always pessimistic. Since OpenJPA applications expects lock waits as usually is done with normal pessimistic databases, the server should be set to the pessimistic mode. The optimistic mode is about not waiting for the locks at all. That increases concurrency but requires more programming. The pessimistic mode with the READ COMMITTED isolation level (default) should get as much concurrency as one might need. The pessimistic locking mode can be set in solid.ini: [General] Pessimistic=yes One can override the locking mode on the per table base by setting OpenJPA property "openjpa.jdbc.DBDictionary" to value "lockingMode=PESSIMISTIC" in the persistence.xml. An extra SQL will be generated along with CREATE TABLE DDL: ALTER TABLE EX_POBJECT SET PESSIMISTIC. The possible values for lockingMode is OPTIMISTIC/PESSIMISTIC.

## Sybase Adaptive Server

Example properties for Sybase

    openjpa.ConnectionDriverName: com.sybase.jdbc2.jdbc.SybDriver
    openjpa.ConnectionURL: \
        jdbc:sybase:Tds:SERVER_NAME:4100/DB_NAME?ServiceName=DB_NAME&BE_AS_JDBC_COMPLIANT_AS_POSSIBLE=true

### Known issues with Sybase

- The "`DYNAMIC_PREPARE`" parameter of the Sybase JDBC driver cannot be used with OpenJPA.

- Datastore locking cannot be used when manipulating many-to-many relations using the default OpenJPA schema created by the schematool, unless an auto-increment primary key field is manually added to the table.

- Persisting a zero-length string results in a string with a single space character being returned from Sybase, Inc.'s JDBC driver.

- The `BE_AS_JDBC_COMPLIANT_AS_POSSIBLE` is required in order to use datastore (pessimistic) locking. Failure to set this property may lead to obscure errors like " `FOR UPDATE can not be used in a SELECT which is not part of the declaration of a cursor or which is not inside a stored procedure.` ".

- Applications performing update/insert data of the BigDecimal Java type may fail with OptimisticException if the data exceeds the scale or precision of the column on Sybase. To avoid this problem, applications can specify the precision and scale for the numeric type by setting numericTypeName='NUMERIC(p,s)' for the column type mapped by the BigDecimal Java type. See openjpa.jdbc.DBDictionary for more detail. Alternatively, application can set the precision and scale using the standard Column annotation, described in .