This is the Official Oracle JDBC FAQ.

You can find it on the OTN website at http://otn.oracle.com/tech/java/sqlj_jdbc/htdocs/jdbc_faq.htm.

It is maintained by the Oracle JDBC Development Team with the invaluable assistance of other Oracle Development Teams, the Oracle Java Platform Product Managers, and the Oracle Support Organization.

Material related to Oracle Database 11.1 was added and older material was moved to the Version specific section.

JDBC technology is an API that lets you access virtually any tabular data source from the Java programming language. It provides cross-DBMS connectivity to a wide range of SQL databases, and now, with the new JDBC API, it also provides access to other tabular data sources, such as spreadsheets or flat files.

—From Sun's JDBC page.

A good place to start is Sun's JDBC page.

There are lots of books on JDBC. A good place to start is JDBC API Tutorial and Reference, Third Edition.

You can find out more about Oracle's JDBC drivers in particular from OTN's SQLJ & JDBC pages, from Oracle's online documentation, JDBC Sample Code, and from books such as the highly recommended Expert Oracle JDBC Programming and Oracle Database Programming Using Java and Web Services.

A good place to start is Sun's Java site.

There are lots of books on Java. A few of the more popular ones are:

• Core Java 2, Volume 1: Fundamentals
• Java in a Nutshell
• Effective Java Programming Language Guide–2nd Edition

Oracle provides four different types of JDBC drivers, for use in different deployment scenarios. The 11.1.0 drivers can access Oracle 9.0.1 and higher. While all Oracle JDBC drivers are similar, some features apply only to JDBC OCI drivers and some apply only to the JDBC Thin driver.

• JDBC OCI client-side driver: This is a JDBC Type 2 driver that uses Java native methods to call entrypoints in an underlying C library. That C library, called OCI (Oracle Call Interface), interacts with an Oracle database. The JDBC OCI driver requires an Oracle client installation of the same version as the driver.

  The use of native methods makes the JDBC OCI driver platform specific. Oracle supports Solaris, Windows, and many other platforms. This means that the Oracle JDBC OCI driver is not appropriate for Java applets, because it depends on a C library.

  Starting from 10.1.0, the JDBC OCI driver is available for install with the OCI Instant Client feature, which does not require a complete Oracle client-installation. Please refer to Oracle Call Interface for more information.

• JDBC Thin client-side driver: This is a JDBC Type 4 driver that uses Java to connect directly to Oracle. It implements Oracle's SQL*Net Net8 and TTC adapters using its own TCP/IP based Java socket implementation. The JDBC Thin driver does not require Oracle client software to be installed, but does require the server to be configured with a TCP/IP listener.

  Because it is written entirely in Java, this driver is platform-independent. The JDBC Thin driver can be downloaded into any browser as part of a Java application. (Note that if running in a client browser, that browser must allow the applet to open a Java socket connection back to the server.)

• JDBC Thin server-side driver: This is another JDBC Type 4 driver that uses Java to connect directly to Oracle. This driver is used internally within the Oracle database. This driver offers the same functionality as the client-side JDBC Thin driver (above), but runs inside an Oracle database and is used to access remote databases.

  Because it is written entirely in Java, this driver is platform-independent. There is no difference in your code between using the Thin driver from a client application or from inside a server.

• JDBC Server-Side Internal driver: This is another JDBC Type 2 driver that uses Java native methods to call entrypoints in an underlying C library. That C library is part of the Oracle server process and communicates directly with the internal SQL engine inside calls and thus avoiding any network traffic. This allows your Java code running in the server to access the underlying database in the fastest possible manner. It can only be used to access the same database.

  The use of native methods makes the JDBC Server-Side Internal driver platform specific. This server-side internal driver is fully consistent with the client-side drivers and supports the same features and extensions.

• JDBC 9.0.1 drivers can talk to RDBMS
  • 11.1.0
  • 10.2.0
  • 10.1.0
  • 9.2.0
  • 9.0.1
  • 8.1.7
  • 8.1.6
  • 8.1.5
  • 8.0.6
  • 8.0.5
  • 8.0.4
  • 7.3.4
• JDBC 9.2.0 drivers can talk to RDBMS
  • 11.1.0
  • 10.2.0
  • 10.1.0
  • 9.2.0
  • 9.0.1
  • 8.1.7
• JDBC 10.1.0 drivers can talk to RDBMS
  • 11.1.0
  • 10.2.0
  • 10.1.0
  • 9.2.0
  • 9.0.1
  • 8.1.7
• JDBC 10.2.0 drivers can talk to RDBMS
  • 11.1.0
  • 10.2.0
  • 10.1.0
  • 9.2.0
  • 9.0.1
  • 8.1.7
• JDBC 11.1.0 drivers can talk to RDBMS
  • 11.1.0
  • 10.2.0
  • 10.1.0
  • 9.2.0
  • 9.0.1

A related question is about versions NOT listed here. If its not listed here, its not supported. You should verify with your support channel that you are still on a supported version of Oracle. For example, a lot of people have asked about 8.1.7 which has been desupported. People still using 8.1.7 need to contact their support channels for upgrade info (some of these upgrades are free!).

• pre-8i OCI and THIN Drivers - JDK 1.0.x and JDK 1.1.x
• 8.1.5 OCI and THIN Drivers - JDK 1.0.x and JDK 1.1.x
• 8.1.6SDK THIN Driver - JDK 1.1.x and JDK 1.2.x (aka Java2)
• 8.1.6SDK OCI Driver - Only JDK 1.1.x
• 8.1.6 OCI and THIN Driver - JDK 1.1.x and JDK 1.2.x
• 8.1.7 OCI and THIN Driver - JDK 1.1.x and JDK 1.2.x
• 9.0.1 OCI and THIN Driver - JDK 1.1.x, JDK 1.2.x and JDK 1.3.x
• 9.2.0 OCI and THIN Driver - JDK 1.1.x, JDK 1.2.x, JDK 1.3.x, and JDK 1.4.x
• 10.1.0 OCI and THIN Driver - JDK 1.2.x, JDK 1.3.x, and JDK 1.4.x
• 10.2.0 OCI and THIN Driver - JDK 1.2.x, JDK 1.3.x, JDK 1.4.x, and JDK 5.0.x
• 11.1.0 OCI and THIN Driver - JDK 1.5.x and JDK 1.6.x

Please note that JDK 1.4 is not supported by the 11.1.0 drivers.

The Server Thin Driver and Server Internal Driver support the same version of Java as is supported by the Oracle Server VM.

• Oracle 8i supports J2SE 1.1
• Oracle 9i R1 supports J2SE 1.2
• Oracle 91 R2 supports J2SE 1.3
• Oracle 10g supports J2SE 1.4
• Oracle 11 supports JSE 5

Oracle 9.0.1 supports:

JDBC 2.0 Extensions except for:
• using both global and local transactions on the same connection.

Oracle 9.2.0 supports:

Partial support for JDBC 3.0:
• transaction savepoints
• using both global and local transactions on the same connection.

Oracle 10.1.0 supports:

Full support for JDBC 3.0 except for:
• retrieving auto-generated keys
• result-set holdability
• returning multiple result-sets.

Oracle 10.2.0 supports:

Full support for JDBC 3.0
Note that there is no real change in the support for the following in the database. All that has changed is that some methods that previously threw SQLException now do something more reasonable instead.
• result-set holdability
• returning multiple result-sets.

Oracle 11.1.0 supports:

Full support for JDBC 3.0 in the JDK 1.5 drivers.
Full support for JDBC 4.0 in the JDK 1.6 drivers with the exception of SQLXML which is not supported.

Use the Thin driver unless there is a reason to use something else.

If you are writing an applet, you must use the Thin driver.

If you are using a non-TCP/IP network you must use the OCI driver.

If you are running in the Oracle server, then you should use the Server Internal Driver unless you need to connect to another Oracle database server or to open a second session on the same server. In either of these cases you should use the Server Thin Driver.

Generally the Thin driver is the best choice. In most cases it is as fast or faster than the OCI driver (from 10.1.0), has almost exactly the same set of features, and is easier to administer. In a few cases the OCI driver has slightly better performance. The OCI driver supports a few Oracle features better than the Thin driver. The Thin driver is easier to administer since it does not require installation of the OCI C libraries. The Thin driver will work on any machine that has a suitable Java VM, whereas with the OCI driver you must install the proper OCI C libraries for each machine. We recommend using the Thin driver unless you must have one or more of the OCI only features, or until it is clear that the small performance gain provided by the OCI driver is worth the extra effort.

You can get the classes files from the Oracle Technology Network SQLJ & JDBC Download Page.

Since the Thin driver is 100% Pure Java--Write Once, Run Anywhere--you can use the jar files on any platform that has an appropriate Java VM. The orai18n.jar (previously nls_charset) files are 100% Java so the same files are used for all platforms. The shared library files (.so, .dll) are platform specific so you must use the file appropriate for your platform. These are available in the OCI Instant Client installation. Only the Solaris, Linux, and NT shared libraries are available for download on OTN. You will have to get the share libraries for other platforms from the Oracle client installation CD for that platform.

There are a large number of classes files that are part of the Oracle JDBC installation.

ojdbc5.jar

All the classes to support basic functionality for the Thin and OCI drivers when using JDK 1.5 (JSE 5). Additional jar files are required when you use some features.

ojdbc5_g.jar

Same as ojdbc5.jar except compiled with the -g option to include debugging information and with java.util.logging calls included.

ojdbc5dms.jar

Same as ojdbc5.jar except includes code to support Oracle Dynamic Monitoring Service (DMS). Also includes some JDBC logging support. This file can only be used when dms.jar is also in the classpath. The dms.jar file is not shipped as part of the RDBMS product. It is only available as part of the Oracle Application Server product.

ojdbc5dms_g.jar

Same as ojdbc5dms.jar except compiled with the -g option to include debugging information and with full JDBC logging support.

ojdbc6.jar

All the classes to support basic functionality for the Thin and OCI drivers when using JDK 1.6 (JSE 6). Additional jar files are required when you use some features.

ojdbc6_g.jar

Same as ojdbc6.jar except compiled with the -g option to include debugging information and with java.util.logging calls included.

ojdbc6dms.jar

Same as ojdbc6.jar except includes code to support Oracle Dynamic Monitoring Service (DMS). Also includes some JDBC logging support. This file can only be used when dms.jar is also in the classpath. The dms.jar file is not shipped as part of the RDBMS product. It is only available as part of the Oracle Application Server product.

ojdbc6dms_g.jar

Same as ojdbc6dms.jar except compiled with the -g option to include debugging information and with full JDBC logging support.

libocijdbc<major_version_id>.so (Solaris)

Native library for the JDBC OCI driver.

• for JDBC 8.x.x drivers, the <major_version_id> is 8
• for JDBC 9.x.x drivers, the <major_version_id> is 9
• for JDBC 10.x.x drivers, the <major_version_id> is 10
• for JDBC 11.x.x drivers, the <major_version_id> is 11

This file should be locatable via your LD_LIBRARY_PATH setting.

ocijdbc<major_version_id>.dll (Windows)

Similar to above, except on Windows platforms. This file should be locatable via your %PATH% setting.

libheteroxa<major_version_id>.so (Solaris)

Auxiliary native library for the JDBC OCI driver, for the native-XA (or Hetero-RM) feature. This library is only available for JDBC 9.x.x, 10.x.x, and 11.x.x drivers. When using this feature, this library should be locatable via your LD_LIBRARY_PATH setting, along with libocijdbc<major_version_id>.so.

heteroxa<major_version_id>.dll (Windows)

Similar to above, except on Windows platforms. When using OCI native-XA, this file should be locatable via the %PATH% setting, along with ocijdbc<major_version_id>.dll.

orai18n.jar

Contains the configuration information to support all Oracle character sets in Advanced Data Types (objects). If the database character set is one other than US7ASCII, W8DEC, WE8ISO8859P1, or ShiftJIS, and the application uses ADTs, then you must include this file in your classpath. It is possible to use your favorite zip utility to delete unneeded files from the jar, but not easy. See orai18n.jar is too big. How do I make it smaller?

This file is still required under the circumstances described above, but it is not technically part of the JDBC drivers. It is available on the JDBC dowrload page or you can get it as part of the Oracle Globalization Kit.

Some older (pre 11.1.0) versions of Oracle JDBC included some of the following files. These files are not shipped in Oracle Database 11 either because they are no longer supported or because they are no longer needed.

classes111.jar

Classes for the Thin and OCI drivers when using a Java 1.1 VM. Includes support for all Oracle character sets as simple columns and for US7ASCII, W8DEC, and ShiftJIS in Advanced Data Types (objects).

classes111.zip

Same as classes111.jar except in zip format. Useful because some VMs can't read jar files.

classes111_g.jar

Same as classes111.jar except compiled with the -g option to include debugging information and with Oracle JDBC logging included.

classes111_g.zip

Same as classes111_g.jar except in zip format. Useful because some VMs can't read jar files.

classes12.jar

Classes for the Thin and OCI drivers when using a Java 1.2 or 1.3 VM.

classes12.zip

Same as classes12.jar except in zip format. This file will almost certainly not be available in future releases. You should use classes12.jar instead.

classes12_g.jar

Same as classes12.jar except compiled with the -g option to include debugging information and with Oracle JDBC logging included.

classes12_g.zip

Same as classes12_g.jar except in zip format. Useful because some VMs can't read jar files.

classes12dms.jar

Same as classes12.jar except includes code to support DMS, Oracle Dynamic Monitoring Service. This file can only be used when dms.jar is also in the classpath. The dms.jar file is not shipped as part of the RDBMS product. It is only available as part of the Oracle Application Server product.

classes12dms_g.jar

Same as classes12dms.jar except compiled with the -g option to include debugging information and with Oracle JDBC logging included.

ojdbc14.jar

Same as classes12.jar except for use with Java 1.4 VMs. Beginning with this file, Oracle JDBC classes files will be named ojdcbXX.jar, where XX is the Java version number. The classes12 files will not be renamed. We will not provide zip files for Java 1.4 and beyond.

ojdbc14_g.jar

Same as ojdbc14.jar except compiled with the -g option to include debugging information and with java.util.logging calls included.

ojdbc14dms.jar

Same as ojdbc14dms.jar except includes code to support DMS, Oracle Dynamic Monitoring Service. This file can only be used when dms.jar is also in the classpath. The dms.jar file is not shipped as part of the RDBMS product. It is only available as part of the Oracle Application Server product.

ojdbc14dms_g.jar

Same as ojdbc14dms.jar except compiled with the -g option to include debugging information and with java.util.logging calls included.

nls_charset11.jar

Contains the classes to support all Oracle character sets in Advanced Data Types (objects) when using a Java 1.1 VM. If the database character set is one other than US7ASCII, W8DEC, or ShiftJIS, and the application uses ADTs, then you must include this class in your classpath. Or you can unzip this file and add the appropriate file to your classpath. The files are named with the Oracle character set number.

nls_charset11.zip

Same as nls_charset11.jar except in zip format. Useful because some VMs can't read jar files.

nls_charset12.jar

Same as nls_charset11.jar except for use with Java 1.2, 1.3, and 1.4 VMs. Not used with Oracle 10.1.0 and later. Use orai18n.jar instead.

nls_charset12.zip

Same as nls_charset12.jar except in zip format. Useful because some VMs can't read jar files.

Both of these drivers run only in the Oracle Server Java VM and their classes are installed as part of installing the VM. There are no separate classes files available or needed for these drivers.

Yes, if it isn't already obvious.

For more details, see the JDBC Y2K paper.

Yes.

The actual .jar files are identical on all platforms. We only build these on one platform, and just copy them over to the others. The only difference is the .so (or .dll) file that is called by the OCI client. The .jar files are identical and can be swapped around between platforms if you want.

A third party software company (and Oracle partner) wanted to know if they could distribute the Oracle JDBC drivers with their application to their own customers. This is a legal question, rather then a technical one. I'm no legal expert, but the PMs here tell me that the short answer is yes so long as you follow the licensing terms spelled out at http://www.oracle.com/technology/software/htdocs/distlic.html.

For something legally binding, get a lawyer or contact your local Oracle sales rep for more details.

Follow the directions in the 10.2.0.1.0 or later version of the Oracle JDBC Developer's Guide. The instructions in the 10.1.0 documentation are incorrect. If you do not have access to the 10.2.0.1.0 or later Developer's Guide, then you can follow the instructions here.

If you wish to reduce the size of orai18n.jar, proceed as follows.

The file orai18n.jar contains many important character set and globalization support files. Instead of extracting only the character set glb files that your application uses, follow this three-step process:

1. Unpack orai18n.jar into a temporary directory

2. Delete all files in your temporary directory EXCEPT the character set glb files that your application uses AND the following 18 class files:
   oracle/i18n/util/ClassLoaderChooser.class oracle/i18n/util/ConverterArchive.class oracle/i18n/util/GDKMessage.class oracle/i18n/util/GDKOracleMetaData.class oracle/i18n/util/OraClassLoader.class oracle/i18n/util/OraResourceBundle.class oracle/i18n/util/message/Messages.class oracle/i18n/text/converter/CharacterConverter12Byte.class oracle/i18n/text/converter/CharacterConverterOGS.class oracle/i18n/text/converter/CharacterConverter1Byte.class oracle/i18n/text/converter/CharacterConverterGB18030.class oracle/i18n/text/converter/CharacterConverterJAEUC.class oracle/i18n/text/converter/CharacterConverterLC.class oracle/i18n/text/converter/CharacterConverterLCFixed.class oracle/i18n/text/converter/CharacterConverterZHTEUC.class oracle/i18n/text/converter/CharacterConverter2ByteFixed.class oracle/i18n/text/converter/CharacterConverterSJIS.class oracle/i18n/text/converter/CharacterConverterShift.class

   The character set glb files are located in oracle/i18n/data/ and named in the format, lx20<OracleCharacterSetId>.glb; where <OracleCharacterSetId> is the hexadecimal representation of the Oracle character set ID. The decimal representation of this ID can be found by the SQL function, NLS_CHARSET_ID. For example, if your application connect to a JA16SJIS database, the following SQL would return 832 in decimal representation.

   select NLS_CHARASET_ID('ja16sjis') from DUAL;

   Manually convert this decimal value to hexadecimal value and get 340. Therefore, you should save oracle/i18n/data/lx20340.glb in your temporary directory together with the 15 class file above.

   In your temporary directory, ensure you have the same directory structure as the original package. All glb files and the 15 class files are distributed in

   oracle/i18n/data/	(lx20<OracleCharacterSetId>.glb files)
   oracle/i18n/util/	(3 class files)
   oracle/i18n/util/message/	(1 class files)
   oracle/i18n/text/converter/	(11 class files)

3. Create a new jar file from the temporary directory using a different file name other than orai18n.jar and add the new jar file to your CLASSPATH.

The drivers create a number of different threads, but only on an as-needed basis. They do not create the threads unless your code makes use of the feature that depends on the thread. All of these threads are daemon threads.

• Statement timeout thread. This thread is created if you execute any statement with a timeout. Only one thread is created no matter how many statements or connections. This thread lasts the lifetime of the VM.
• Implicit Connection Cache timeout thread. Used to enforce timeouts on the connection cache, and is enabled when at least one timeout property on the connection cache is enabled. There is one thread per connection cache. It lasts the lifetime of that connection cache.
• Fast Connection Failover Event handler thread. Listener thread to receive HA events from RAC. Started only when FCF is enabled. There is one thread per connection cache. It lasts the lifetime of that connection cache.
• FCF worker thread Processes UP/DOWN events. Started only when the events are being processed, and terminates after it is done its job.
• Runtime Load Balancing Event Handler thread. This is the listener thread that receives RLB events from RAC. Started only when FCF is enabled. There is one thread per connection cache. It lasts the lifetime of that connection cache.
• RLB Gravitate connection cache thread. This is started only when RLB is enabled, and when there is a need to gravitate connections in the cache to healthy instances. The thread terminates after it has finished its job.
• OracleConnectionCacheImpl timeout thread. Deprecated. Started only when this old cache is used, to enforce timeouts on the old cache. There is one thread per connection cache. It lasts the lifetime of that connection cache.

When your application is run with a SecurityManager enabled (which it should in production) certain operations are priviliged. In order to do those operations the code must be granted the appropriate permissions. What permissions do the Oracle JDBC drivers require?

As usual, it depends. It depends on what you are trying to do. Beginning with 10.2 the drivers do the right thing when the SecurityManager is enabled. This requires quite a long list of permissions. In a secure environment you only want to grant the necessary permissions, so which permissions you grant depends on what your application is asking the drivers to do.

The way to find out what permissions to grant is to look at the file ojdbc.policy in the demo directory. This is a generic security policy file that you can use to grant the drivers all the necessary permissions. In most cases you will want to comment out many of the permissions since your app doesn't use the features that requires those permissions.

This file depends on a number of system properties. To use this file you will have to define those properties using the -D option to the java command.

Some of the permissions need only be granted to the JDBC driver code. The operations that require those permissions are enclosed in a doPriviliged block. Other permissions must also be granted to the code that calls the drivers. Those operations are not enclosed in doPriviliged blocks. Which is which was chosen so as to make it as difficult as possible to use the drivers to cause mischief. One noteworthy example is that the calling code needs the open socket permission when using the thin driver to open a connection. This is to prevent rogue code from using the drivers for a denial of service attack, among other reasons.

The classes in the package oracle.jdbc.driver are desupported in 11.1. You should use the types in the package oracle.jdbc instead. Typically all that is required is to replace oracle.jdbc.driver with oracle.jdbc. If that doesn't work then your code is using classes or methods that were never intended for public use. You will have to find another solution. There is no workaround or backward compatibility mode.

The package oracle.jdbc was introduced in 8.1.7. In 9.0.1 we deprecated the package oracle.jdbc.driver and updated all the documentation to refer to oracle.jdbc. At that time we also started telling people that oracle.jdbc.driver would be desupported. That was over six years ago. Every release since then has warned that oracle.jdbc.driver was going to be desupported. Two years ago we announced on the JDBC OTN page and forum that 11.1 would desupport oracle.jdbc.driver. And so it does.

We take backward compatibility very seriously, but there have been many changes in Oracle, Java, and JDBC since the first release of the drivers. For a variety of reasons it has long been necessary for us to desupport customer use of the implementation classes that are contained in oracle.jdbc.driver. We have been trying to get the word out for over six years. We are sorry that you are having problems, but we had to make this step.

See the answer to the previous question.

Customer use of the package is desupported. We did not remove the package or the classes it contains. This package is the core implementation code for the driver. We could have renamed the package but did not because it would have been a lot of work for not much gain.

What we did do is change the visibility of the classes and methods in the package. Most of the classes are now default (package) visible instead of public visible. Many of the internal implementation methods used to be public visible. Most are now more restricted. These are the changes that would cause source to give compile errors or compiled code to throw runtime errors.

Yes.

The class oracle.jdbc.pool.OracleConnectionCacheImpl has also been desupported. We only gave a couple of years notice about this. Use the Oracle Implicit Connection Cache instead. It is documented in the Oracle JDBC Developer's Guide.

This approach to connection caching proved very problematic. Basically we couldn't get it to work reliably and it is a poor design. We have only limited resources and OracleConnectionCacheImpl was a huge resource sink. We wanted to use our resources on projects with more long term benefit to our customers, so we had to let it go.

Put the jar files in a convenient location and include the appropriate jar files in your classpath. See What are all these files for? to determine which files you need.

The JDBC OCI driver generally requires an Oracle client-installation of the same version the driver. Starting from 10.1.0, the JDBC OCI driver is available for install with the OCI Instant Client feature, which does not require a complete Oracle client-installation. Please see "What are all of these files for" for details. Also refer to the documentation on OCI Instant Client install.