Oracle DB Installation

Drivers

Requirements

• You will need the following items from your package manager (linux)
  • PHP Pear and PHP Dev (for PECL)
  • Development tools / (e.g. Build Essential tools)
  • libaio1
• For Windows you will just need an OCI8 dll file from PHP PECL (or from Bitnami)
• Oracle Instant Client Files
  • Download the basic and sdk instant client files: Oracle Instant Client Downloads
  • Example Filenames:
    • instantclient-basic-linux.x64-12.1.0.2.0.zip
    • instantclient-sdk-linux.x64-12.1.0.2.0.zip

Driver Install

• In Linux you will need to use PECL to build the OCI8 module, pointing to the unzipped instant client files as the library. Then enable the module in PHP.
• In Windows you will need to add the unzipped instant client files to your PATH variable and restart the machine. Then enable the module in PHP.

For concrete examples, see the Ubuntu 16.04 instructions or the Bitnami Windows instructions.

Oracle Instant Client Instructions for Linux

Begin by navigating to http://www.oracle.com/technetwork/database/database-technologies/instant-client/downloads/index.html and download an appropriate Oracle Instant Client and SDK. You can't download these files directly from your Linux server because Oracle requires you to accept a license agreement and additionally sign into your Oracle account (free registration) before completing the download.

Download the desired packages. For instance on Ubuntu, Debian, and other Linux variants we've downloaded the following packages:

• instantclient-sdk-linux.x64-18.3.0.0.0dbru.zip
• instantclient-basic-linux.x64-18.3.0.0.0dbru.zip

SSH into your Linux machine and create the following directory:

$ mkdir /opt/oracle

Upload the Oracle packages to your server and then move them into the 'oracle' directory and unzip both, beginning with the basic (non SDK) package:

$ mv instantclient-basic-linux.x64-18.3.0.0.0dbru.zip /opt/oracle
$ mv instantclient-sdk-linux.x64-18.3.0.0.0dbru.zip /opt/oracle
$ cd /opt/oracle
$ unzip instantclient-basic-linux.x64-18.3.0.0.0dbru.zip
$ unzip instantclient-sdk-linux.x64-18.3.0.0.0dbru.zip

It is important to follow this sequence because the SDK package will unzip into the directory created by the basic package. If you're using a fresh Linux instance you may need to install the unzip package.

Next you'll add the instant client directory to ldconfig:

$ touch /etc/ld.so.conf.d/oracle-instantclient

Open this newly created file and add the following line:

/opt/oracle/instantclient_18_3

Next you'll need to install a few PHP and system packages. Use your package manager to do so, on Debian/Ubuntu you'd use apt install for instance:

$ apt install php-dev php-pear php-xml build-essential libaio1

If you're running an earlier version of PHP (for example 7.1) then you will need to modify the PHP package names to look like php7.1-dev, php7.1-pear, etc.

Next, install the oci8 PHP extension:

$ pecl install oci8
downloading oci8-2.1.8.tgz ...
Starting to download oci8-2.1.8.tgz (194,154 bytes)
.................................done: 194,154 bytes
11 source files, building
running: phpize
Configuring for:
PHP Api Version:         20170718
Zend Module Api No:      20170718
Zend Extension Api No:   320170718
Please provide the path to the ORACLE_HOME directory. Use 'instantclient,/path/to/instant/client/lib' if you're compiling with Oracle Instant Client [autodetect] : instantclient,/opt/oracle/instantclient_18_3

IMPORTANT: Note you are prompted to provide the path to the 'ORACLE_HOME' directory. The required format is rather odd, and it must be followed precisely. You must specify the string 'instantclient' followed by a comma, followed by the path to the instantclient directory. For example:

instantclient,/opt/oracle/instantclient_18_3

After entering the string and pressing enter, installation output will scroll by, concluding with:

...
Build process completed successfully
Installing '/usr/lib/php/20180731/oci8.so'
install ok: channel://pecl.php.net/oci8-2.2.0
configuration option "php_ini" is not set to php.ini location
You should add "extension=oci8.so" to php.ini

Per the output direction, you'll need to add the extension reference to your 'php.ini' file. You likely have *two* 'php.ini' files on your server, one for the CLI and one for the web server. You can learn more about their locations by running:

$ find / -name php.ini
/etc/php/7.2/cli/php.ini
/etc/php/7.2/fpm/php.ini

On this particular server there are two 'php.ini' files; one for the CLI and another for PHP-FPM. The PHP-FPM 'php.ini' file is associated with the web server so we'll want to update it to include the 'extension=oci8.so' line, however for testing purposes it's useful to update both configuration files. Open the file and append the following line to each:

extension=oci8.so

After saving the files, run the following command to confirm the PHP CLI sees the OCI8 extension:

$ php -m | grep oci
oci8

Finally, add the following two variables to your system environment and to Apache envvars file:

export LD_LIBRARY_PATH=/opt/oracle/instantclient_18_3
export ORACLE_HOME=/opt/oracle/instantclient_18_3

If you're running NGINX, you can define these variables in the NGINX configuration file:

location ~ \.php$ {
     ...
     fastcgi_param LD_LIBRARY_PATH /opt/oracle/instantclient_18_3;
     fastcgi_param ORACLE_HOME /opt/oracle/instantclient_18_3;
 }

Remember you'll need to restart your web server to ensure any changes to the web-related php.ini file take effect. Once complete, you should be able to generate an Oracle API via your DreamFactory web administration console.

For testing purposes you might additionally consider downloading the SQL Plus client (instantclient-sqlplus-linux.x64-18.3.0.0.0dbru.zip) to ensure your DreamFactory server can connect to the Oracle database. You'll download this zip file from the aforementioned Oracle website. Be sure to move the file to /opt/oracle, and then unzip it into /opt/oracle/instantclient_18_3. After unzipping it, make sure the following environment variables are set:

$ export ORACLE_HOME=/opt/oracle/instantclient_18_3
$ export LD_LIBRARY_PATH="$ORACLE_HOME"
$ export PATH="$ORACLE_HOME:$PATH"

After setting these variables, you can start SQL Plus like so:

$ sqlplus

Don't Need Oracle?

DreamFactory's Silver and Gold licenses include the Oracle connector by default, however if you don't require Oracle support and therefore don't install the OCI8 extension then you'll encounter the following error:

Problem 2
 - Installation request for yajra/laravel-oci8 v5.5.8 -> satisfiable by yajra/laravel-oci8[v5.5.8].
 - yajra/laravel-oci8 v5.5.8 requires ext-oci8 >=2.0.0 -> the requested PHP extension oci8 is missing from your system.

You can forgo the Oracle extension requirement by following these instructions:

Open composer.json and delete this block:

{ 
  "type": "vcs",
  "url":  "https://github.com/dreamfactorysoftware/df-oracledb"
},

Scroll further down composer.json, and remove the line beginning with dreamfactory/df-oracledb":

When removing these lines, be sure to remove the concluding comma, and leave the preceding comma intact.

Save your changes, and run the following command from your project's root directory:

$ composer update dreamfactory/df-oracledb --ignore-platform-reqs

If you instead run composer install --ignore-platform-reqs after making this change, you'll see the following warning:

Warning: The lock file is not up to date with the latest changes in composer.json. You may be getting outdated 
dependencies. Run update to update them.

This isn't a particularly big deal, however in the interests of ensuring your composer.json and composer.lock files are synchronized, run the aforementioned composer update command after the composer install command completes, at which point you are done.