Installing Oracle Instant Client 12.1 and cx_Oracle on macOS Sierra

First off, download the Instant Client, either Basic or Basic Lite. I usually opt for Basic Lite because it’s all I need, but if you work in a language other than English you might want Basic. Also grab the SDK package a few rows down. I also recommend getting sqlplus, because it’s nice to have a CLI sometimes and your DBA will be impressed.

Now fire up Terminal and run a few things. It should Just Work as long as you’ve downloaded everything to ~/Downloads.

# make a home for oracle and go there
mkdir -p ~/Library/Oracle && cd $_

# unzip everything
unzip '~/Downloads/instantclient-*.zip'

# create some symlink
ln -s libclntsh.dylib.12.1 libclntsh.dylib

At this point you should be able to run ./sqlplus from that same directory we were just in. If that didn’t work, try repeating those steps.

Usually at this point I grab SQL Developer and try connecting to something. It’s my sanity check before I delve into the mysteries of cx_Oracle. Oh btw, if you haven’t used SQL Developer before you should. It’s a pretty sweet client for working with Oracle databases. (Big caveat: if you fire it up and nothing happens, you probably need the JRE).

Now it’s time to install cx_Oracle. Whoa there hoss, you can’t just pip install cx_Oracle. That’s crazy talk. We need to set some envvars in our .bash_profile first. I’ll explain what they are first, followed by a snippet of exactly what to add.

The first of these is pretty straightforward: ORACLE_HOME. This is where we put the Instant Client.

The other one is DYLD_LIBRARY_PATH. I always thought this was some obscure Oracle thing, but it turns out it’s an OS-level setting that we probably shouldn’t be messing with. If you spend hours trying to find a sane recommendation on this (like I did), well, you won’t. Some tutorials say to just clobber it, and other people have written shell scripts to rewrite the dependency paths in the Instant Client. My resolution was to use the variable, but at least append to it rather than replacing it the whole thing, in case there happens to be something in there.

So add these lines to your ~/.bash_profile:

# Oracle
export ORACLE_HOME=~/Library/Oracle/instantclient_12_1

Guess what? It’s pip time. Go ahead and pip install cx_Oracle. It shouldn’t give you any issues.

When I first tried connecting I got an error ORA-21561: OID generation failed. The solution was to add my local hostname to /etc/hosts; see this blog post for more.

And that’s a wrap! At some point I’d like to add notes on how to set up things like tnsnames and LDAP, but I haven’t gotten there yet. If anyone has any questions or suggestions, feel free to comment below.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s