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
# 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
# Oracle export ORACLE_HOME=~/Library/Oracle/instantclient_12_1 export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:$ORACLE_HOME export PATH=$PATH:$ORACLE_HOME
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.