Oracle

This connector provides functionality for Oracle databases.

It is included by default in AWS/Azure/Docker/VM enterprise distributions.

Important

This feature is only available in Professional Edition or higher

Installation and Configuration

SlashDB version >= 2.0.0 must be installed before the connector can be installed. If you don't have SlashDB yet, see the Installation documentation.

You must obtain some packages from Oracle before beginning the SlashDB connector installation. Visit the Oracle Instant Client Downloads to download:

Instant Client Basic Package v21
SQL*Plus Package v21

In your download directory, you should have the files:

oracle-instantclient-basic-21.6.0.0.0-1.x86_64.rpm
oracle-instantclient-sqlplus-21.6.0.0.0-1.x86_64.rpm

From System Package

Debian or Ubuntu

Use the root account
```
sudo su
```
Convert the Oracle RPM packages to DEB format using alien

From your download directory:
```
apt-get update
apt-get install alien
alien -v oracle-instantclient-*.rpm
```
Once complete, the download directory will contain new files:
- oracle-instantclient-basic\_21.6.0.0.0-2\_amd64.deb
- oracle-instantclient-sqlplus\_21.6.0.0.0-2\_amd64.deb

Install Oracle DEB packages and set up system environment

apt-get install -y ./oracle*.deb

echo "/usr/lib/oracle/21/client64/lib/" >> /etc/ld.so.conf.d/oracle.conf
ldconfig

echo 'export ORACLE_HOME=/usr/lib/oracle/21/client64' >> /etc/profile.d/oracle.sh
echo 'export PATH=$PATH:$ORACLE_HOME/bin' >> /etc/profile.d/oracle.sh
echo 'export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH' >> /etc/profile.d/oracle.sh
echo 'export NLS_LANG=American_America.UTF8' >> /etc/profile.d/oracle.sh
echo 'export NLS_DATE_FORMAT="yyyy-mm-dd hh24:mi:ss"' >> /etc/profile.d/oracle.sh

. /etc/profile.d/oracle.sh

If your Oracle server runs inside a Docker container and is version 19 or above, you will need to disable the Out-of-Band breaks feature. Add this line to sqlnet.ora:

echo "DISABLE_OOB=ON" >> ~/.sqlnet.ora

Download and install the SlashDB Oracle connector
```
wget -c https://downloads.slashdb.com/versions/2.0.1/slashdb-oracle_1.3.0_amd64.deb
apt-get install -y ./slashdb-oracle_1.3.0_amd64.deb
```
If a specific version of cx_Oracle is needed, set the environment variable CX_ORACLE_VER before installing the connector.
```
export CX_ORACLE_VER=8.3.0; apt-get install -y ./slashdb-oracle_1.3.0_amd64.deb
```
Info

On Ubuntu 24.04 an additional step may be required.

The Oracle client may fail with following error:
```
$ sqlplus -V
sqlplus: error while loading shared libraries: libaio.so.1: cannot open shared object file: No such file or directory 
```
The file libaio.so.1 cannot be found due to a change in the name of the Linux kernel AIO access library from /usr/lib/x86_64-linux-gnu/libaio.so.1 to /usr/lib/x86_64-linux-gnu/libaio.so.1t64.

Until Ubuntu packages are fixed, a workaround is to create a symbolic link:
```
sudo ln -s /usr/lib/x86_64-linux-gnu/libaio.so.1t64 /usr/lib/x86_64-linux-gnu/libaio.so.1
```
With the above change, the Oracle client and SlashDB connections to Oracle databases should work properly.
```
$ sqlplus -V       

SQL*Plus: Release 21.0.0.0.0 - Production
Version 21.6.0.0.0
```
Restart the SlashDB service
```
systemctl restart slashdb
```

SlashDB should now be able to connect to Oracle databases.

Red Hat or Oracle Linux

Use the root account
```
sudo su
```
Install RPM files for Oracle

From your download directory:
```
yum install -y ./oracle-instantclient-*.rpm
```

Set up system environment

echo "/usr/lib/oracle/21/client64/lib/" >> /etc/ld.so.conf.d/oracle.conf
ldconfig

echo 'export ORACLE_HOME=/usr/lib/oracle/21/client64' >> /etc/profile.d/oracle.sh
echo 'export PATH=$PATH:$ORACLE_HOME/bin' >> /etc/profile.d/oracle.sh
echo 'export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH' >> /etc/profile.d/oracle.sh
echo 'export NLS_LANG=American_America.UTF8' >> /etc/profile.d/oracle.sh
echo 'export NLS_DATE_FORMAT="yyyy-mm-dd hh24:mi:ss"' >> /etc/profile.d/oracle.sh

. /etc/profile.d/oracle.sh

Important

If your Oracle server runs inside a Docker container and is version 19 or above, you will need to disable the Out-of-Band breaks feature. Add this line to sqlnet.ora:

echo "DISABLE_OOB=ON" >> ~/.sqlnet.ora

Download and install the SlashDB Oracle connector

dnf install -y https://downloads.slashdb.com/versions/2.0.1/slashdb-oracle-1.3.0.x86_64.rpm

Info

If a specific version of cx_Oracle is needed, set the environment variable CX_ORACLE_VER before installing the connector.

export CX_ORACLE_VER=8.3.0; yum install -y ./slashdb-oracle-1.3.0.x86_64.rpm

Restart the SlashDB service.
```
systemctl restart slashdb
```

SlashDB should now be able to connect to Oracle databases.

From Python Wheel

If SlashDB was installed as a Python package, it is recommended to install the Oracle connector as a Python package in the same environment.

You will need to download the necessary Oracle components as described above.

Available wheel packages:

Download and install the package that matches your version of Python, e.g.:

wget https://downloads.slashdb.com/versions/2.0.1/slashdb_oracle-1.3.0-cp39-cp39-manylinux2014_x86_64.whl
/opt/slashdb/bin/pip install ./slashdb_oracle-1.3.0-cp39-cp39-manylinux2014_x86_64.whl

After installation, SlashDB must be restarted manually.

Adding a Database Instance

In the menu, click on Database Connections, then click the New button in the top right corner
Select the Oracle type from the database selection screen
Fill in the configuration details for your database, then click the Next button

(Oracle configuration uses an SID or Service Name, use the Connection type dropdown list to pick)
Set the database ID and other options for your database connection, then click the Create button

Editing a Database Connection

To edit an existing database connection, go to the Database Connections list and click the Edit icon in the Actions column, or click on the database ID.

The edit form is divided into three sections: Connection, Configuration, Privileges

Connection

Description - an optional description for the connection
Type - the database vendor type
Database Charset - the character set used for string types
Database Schema - the name of the database server schema to use
Database Host - the hostname or IPv4 address of the database server
Connection Type - dropdown to select Service Name or SID
Service Name / SID - Oracle Service Name or SID
Database Port - the port number that the database server listens on
Database Name - the name of the database on the server to use

Configuration

Connect Automatically - automatically connect to the database whenever SlashDB starts
Cache Schema - cache the database schema after the first connection so that subsequent connections complete faster

Important

Whenever your database structure changes, you will need to disable this option, disconnect/reconnect, and then enable it again. If your database structure changes frequently, you may want to disable it entirely.
Auto Discover - automatically find all tables and views in your database whenever SlashDB connects

Database Credentials

Pick one of:

Local - the Database Login and Database Password to use for database reflection
Credential Reference - the Database Credentials to use for database reflection

Privileges

Connect / Disconnect DB - users with privileges to control the database connection
View DB Config - users with privileges to view the database configuration
Modify DB Config - users with privileges to edit or delete the database configuration

Updating

To update, install a newer version of the package.

Important

After updating the core SlashDB RPM/DEB package, you must reinstall plugins