RubyMine 2023.2 Help

Connect to Oracle with OCI

Official documentation and software

RubyMine uses JDBC drivers to connect to the Oracle server through the TNS protocol.

In thin mode, the JDBC driver always connects to the TNS listener. In this mode, various versions of the JDBC driver can be used.

In OCI mode, the JDBC driver uses native libraries. In this case, the JDBC driver's version must be the same as the version of these native libraries.

Prerequisites

  • Oracle Instant Client (OCI) packages: Basic Package, SQL*Plus Package, JDBC Supplement Package. Download packages for your operating system from the Oracle Instant Client Downloads page at oracle.com.

  • Running Oracle instance with access permissions for your user.

  • The configured tnsnames.ora file.

Compatibility of versions in OCI mode

Installation on separate machines

When the Oracle Instant Client is installed on a separate machine, versions of the Oracle Instant Client and Oracle Server may differ. For example, Oracle Client 19.x can successfully connect to Oracle server 11.2. But the JDBC driver must have the same version as the Oracle Instant Client. Otherwise, you will see errors like Native library cannot be loaded or Incompatible version of libocijdbc.

For example, consider the following Oracle setup:

  • Oracle Database 12c Enterprise Edition Release 12.2.0.1.0 - 64bit Production

  • Oracle Instant Client 19.8.0.0

If we use the Oracle driver 19.3.0.0, we are going to get Incompatible version of libocijdbc. But if we switch to Oracle driver 19.8.0.0, the connection will be successful. Consider the following animation.

Installation on the same machine

When the Oracle Instant Client is installed on the machine with the Oracle server, the JDBC driver uses the native library to connect to the Oracle server. And this native library is a part of Oracle server software. So, the JDBC driver must have the same version as the Oracle server.

Summary table

Separate machines

Same machine

Versions of Oracle Instant client and Server

May differ

Will be the same (as the Oracle Instant Client is a part of Oracle server software)

Version of the JDBC driver

Same as the Oracle Instant client

Same version as the Oracle server

Preparing OCI files and environment

From the Oracle Instant Client Downloads page at oracle.com, download the following packages for your operating system:

  • Basic Package

  • SQL*Plus Package

  • JDBC Supplement Package

Step 1. Unpack the downloaded packages

  1. Create a directory (for example, ~/Oracle/instantclient_19_8/).

  2. Extract all packages to the created directory.

Step 2. (Optional) Add environment variables

This step is optional. After the environment variables are being set, you can connect to your Oracle instance with the sqlplus tool. Note that these settings work only for the current session of the command prompt.

  • Add the following environment variables:

    export ORACLE_HOME=~/Oracle/instantclient_19_8
    export TNS_ADMIN=$ORACLE_HOME/network/admin
    export NLS_LANG=English_America.UTF8
    export PATH=$PATH:$ORACLE_HOME
    set ORACLE_HOME=C:\Oracle\instantclient_19_8
    set TNS_ADMIN=%ORACLE_HOME%\network\admin
    set NLS_LANG=English_America.UTF8
    set PATH=%PATH%:%ORACLE_HOME%

Step 3. Configuring ORA files

You can request the tnsnames.ora file from your Oracle server administrator or compose the file by using the following approach:

  1. In the directory that you created on Step 1, create the network directory. Inside the network directory, create the admin directory. The overall path should look as follows: ~/Oracle/instantclient_19_8/network/admin.

  2. In the admin directory, create the tnsnames.ora file with the following structure:

    MyTNSAlias = (DESCRIPTION = (ADDRESS = (PROTOCOL = TCP)(HOST = db.my.domain.com)(PORT = 1521)) (CONNECT_DATA = (SERVER = DEDICATED) (SERVICE_NAME = my_service.my.domain.com) ) )

    Your tnsnames.ora file might have the following look:

    tnsnames.ora

    After you have configured the tnsnames.ora file and environment variables, you can try to connect to the instance by running the following commands:

    cd ~/Oracle/instantclient_19_8
    export TNS_ADMIN=~/Oracle/instantclient_19_8/network/admin
    sqlplus login@MyTNSAlias
    Configuring TNS files

Creating the Oracle OCI connection

Step 1. Prepare a driver for the OCI connection

  1. Open data source properties. You can open data source properties by using one of the following options:

    • In the Database tool window ( View | Tool Windows | Database) , click the Data Source Properties icon The Data Source Properties icon.

    • Press Control+Alt+Shift+S.

  2. In the Data Sources and Drivers dialog, click the Drivers tab.

  3. In the list of drivers, right-click the Oracle driver and select Duplicate.

  4. Change the name of the duplicated Oracle driver (for example, Oracle [OCI]).

  5. In the Driver Files pane, click the Add icon (the Add button) and select Native Library Path….

  6. In the file browser, navigate to the directory of the Instant Client created previously (for example, ~/Oracle/instantclient_19_8) and click Open.

     Preparing drivers for the OCI connection

Step 2. Create the OCI connection

  1. To connect to the database, create a data source that will store your connection details. You can do this using one of the following ways:

    • From the main menu, navigate to File | New | Data Source and select Oracle.

    • In the Database tool window ( View | Tool Windows | Database) , click the New icon (the New icon) in the toolbar. Navigate to Data Source and select Oracle.

    Create a new data source
  2. From the Connection type list, select TNS.

    Select the Connection type
  3. From the Driver list, select OCI.

    Select the OCI driver
  4. Click the Driver link and select the driver entry that you created on Step 1.

    Click the driver link
  5. In the TNSADMIN field, click the browse button and navigate to the directory with the Instant Client (in our case, ~/Oracle/instantclient_19_8/).

  6. In the TNS name field, specify what service name to use (see a value of an alias in tnsnames.ora).

  7. Specify credentials for the Oracle user.

  8. Ensure that the connection to the database can be established using the provided details. To do that, click the Test Connection link at the bottom of the connection details area.

    Test Connection link

    In case of any connection issues, refer to the Cannot connect to a database page.

  9. (Optional) By default, only the default schema is introspected and available to work with. If you also want to work with other schemas, in the Schemas tab, select them for the introspection.

    Schemas tab of the Data Sources and Drivers dialog
  10. Click OK to create the data source.

  11. Find your new data source in the Database tool window (Alt+1) .

    • To learn more about the Database tool window, see the corresponding reference topic.

    • To learn how to work with database objects in RubyMine, see Database objects.

    • To write and run queries, open the default query console by clicking the data source and pressing F4.

    • To view data of a database object, open Data Editor and Viewer by double-clicking the object.

Create the OCI connection
Last modified: 07 July 2023