Step 1: Where to install the Files

Opinions differ about the best location for installing the downloaded files.
In practice you can install the Oracle instant client files anywhere on your file system so long as the PATH environment variable is updated to include that directory in the search path

• Some install instructions suggest copying the install files into the directories:
  /usr/lib or /usr/bin
   
  This works - but is best avoided. My concern with this approach is that these are the default locations for OS X libraries and commands. Copying in non-standard items gets messy when things go wrong - complicating the process to diagnose and fix issues because of the difficulty identifying which items should (and shouldn’t) be there. If you upgrade Instant Client in future, copying in the new version’s files over top may result in a mixture of old/new libraries which triggers unexpected behaviour. However, if you have issues defining environmental variables then this may be your only choice.
   
• In Oracle’s installation example, they’ve created a directory:
  /opt/oracle/instantclient_11_2
   
  This gives you a separate (clearly specified) directory for your Instant Client files. It’s also good choice as /opt is the base directory favoured for non-standard (i.e. optional) software installs in Unix operating systems …but it’s just not commonly used in Mac circles.
   
• My preferred option is:
  /Library/Oracle/instantclient_11_2
   
  This has the advantage of the choice above - but is a more Mac-like alternative. This is the directory I’ll specify for these instructions going forward (but feel free to use whichever location you think is most appropriate for you).

After downloading the three packages above:

1. Extract instantclient-basic and instantclient-plus zip files into single folder (e.g. /Library/Oracle/instantclient_11_2), then
    
2. Create a subfolder named “sdk” inside that folder, and extract instantclient-sdk into it.

Open Mac Terminal. Change to the directory you created, add a symbolic link, and create a network/admin subdirectory (which we’ll later use for our tnsnames.ora file):

Step 2: Defining an ORACLE_HOME and Environmental Variables

Getting Instant Client to function depends on correctly setting up the required environmental variables.These allow the Oracle client to find the files and library routines it needs when required.

You’ll need the following environment variables configured:

• PATH
• CLASSPATH
• DYLD_LIBRARY_PATH
• ORACLE_HOME
• TNS_ADMIN

The first variable (PATH) probably already exists on your Mac, but will need to be modified to add the new directory path which you created for the Instant Client files. The remaining environmental variables will probably be new on your system. Prior to OS X 10.10 Yosemite, we would have set environmental variables in the /etc/launchd.conf file - however, this method no longer works. The workaround is to set these variable in the .bash_profile file associated with your login.

Open Mac Terminal. Move to your home directory (~) and look to see if there’s an existing .bash_profile file. If there is, use the more command to display it’s content.

• The cd ~ command takes you to the home directory for your user.

• The ls .bash_profile command checks to see if there’s an existing file

• The command more .bash_file displays the contents of the file.

If your user account has an existing file, the contents might look a little different (which is okay).
If your user account doesn’t have an existing file then a new empty file can be created using the touch command below. Note that you’ll be asked for the root password since the sudo command is requesting root permissions

Once the file exists, you can load it into your favourite text editor to configure the environmental variables you need for Oracle Instant Client. The edit command will open the file in your default GUI-based text editor such as TextEdit or TextWrangler. Note that other command-line based editors such as nano or vim can also be used (as per the information box at the end of this article).

Update the .bash_profile content to add the new Oracle instant client directory in your PATH variable, and set the other new variables are required. Remember that the specified directory should be the location of the Oracle instant client files that you installed above (i.e. if you’ve used a different location then specify that instead).

The resulting file should look something like that below:

The last item, the NLS_LANG environmental variable, helps specify the language and behaviour (i.e. display of dates and numbers) of your Oracle applications, and should be set to a value appropriate for your region.

Save the updated file when complete.

Step 3: Creating a TNSNAMES.ORA File

The tnsnames.ora file specifies connection details for databases in your environment. It contains database names, server names/addresses and port. Although not so critical in a home environment where you’ll likely only have one or two databases - it’s useful in the corporate world where there are potentially dozens of different systems available to connect to.

Potentially you may already have tnsnames.ora file installed - or might have one provided for you by a system administrator. Even so, you need to ensure that its accessible by locating it in the directory you specified in the TNS_ADMIN variable above. Traditionally (or at least in the Windows world) the file has been located in a network/admin directory underneath the ORACLE_HOME. You don’t necessarily need to keep with this tradition - but you should still make sure that the location can be found.

If you don’t have an existing tnsnames.ora file, you can create one using the same method we used for the .bash_profile file in step 2 above.

Note that we prefixed the edit command with sudo since this helps ensure that the file (and edits) are owned by your system’s root user. The format of the tnsnames.ora content is below.

This lets you specify the database name, host, listener port and SID/Service Name. Just repeat the code block for each database that you wish to specify and connect to.

Example:

Step 4: Setting Permissions for ORACLE_HOME

We now need to specify permissions for the ORACLE_HOME director created in step 1, and referred to by our environmental variables in Step 2. To do this, enter the commands below - modifying the commands as necessary to specify the ORACLE_HOME directory path as per your system.

• The first command sets the group ownership of the Oracle directories and their contents - linking them to the “wheel” group (i.e. root user and anyone with su privileges.)

• The second command changes the privileges to read, write and execute the Oracle contents.

Step 5: Reboot and Test

Although the changes are now complete, you’ll need to restart your Mac for them to take effect.

After the restart, open a terminal window and enter the env command to display the environmental variables for your system. Hopefully these should be consistent with those you set in step 2 above.

You should now (we hope) also be able to get a successful connection to your Oracle databases through SQLplus and (if installed) Oracle SQL Developer.

References

• Daniel Norwood - Connecting to Oracle with Toad. Although specifically written for Toad users, this article contains great general advice on the setup of Oracle instant client.

• Enavigo - Enabling Oracle OCI8 PHP Extension on OS X Snow Leopard. Although out of date, it provides a good overview - including why installing the SDK is useful. However, this article’s recommendation to copy Instant Client files into /usr/bin and /usr/lib is best avoided IMHO.