Build and install cx_Oracle on MacOS X Leopard Intel

I recently decided to write a few tools to automate some boring database management tasks. Since I am not attached to any particular technology, I decided to do take the opportunity to get to know the Django web framework. Getting a simple server up and running is as easy as doing the same with the Rails framework. In order to do something useful, one needs to integrate a database system, which in my case is Oracle 10g.

In Django’s settings.py, one can setup the database engine, which, luckily includes oracle. Unless you already have a working Python-Oracle setup, you will have to install the cx_Oracle Python database adapter first. Prebuilt binaries for Windows and Linux can be downloaded from the Sourceforge archive directly, since I mainly work on a MacBook Pro, I had to build the module by myself.

There are a few little changes I had to make in order to build and install it successfully, which I will describe here. I used the advice on Pedro’s Blog as a starting point and adapted it so that it worked for me.

I. Downloading the required software:

System Requirements:

• Mac OS X Leopard Intel (comes with Python 2.5)
• Xcode (to get the gcc that it contains) from the Apple Developer Connection

To build the module, you need at least the Oracle Instant Client software for MacOS X, which can be downloaded here. The minimum packages that need to be downloaded are the “Basic” and the “SDK” packages.

From the cx_Oracle Sourceforge site, download cx_Oracle-4.3.3.tar.gz (that's the version I used)

II. Unpacking files

I assume that I uncompress my files in /Users/foo/oracle. That’s just my personal setup of course, because I tend to install stuff that I just want to try out under my home folder. Many people would probably put their ORACLE_HOME under /usr/local/oracle.

cd ~/oracle
unzip instantclient-basic-macosx-10.2.0.4.0.zip
unzip instantclient-sdk-macosx-10.2.0.4.0.zip
tar xvfz cx_Oracle-4.3.3.tar.gz

III. Setup of the environment

To my ~/.profile, I added the following lines:

# Setting Oracle development environment
export ORACLE_HOME=/Users/foo/oracle/instantclient_10_2
export DYLD_LIBRARY_PATH=$ORACLE_HOME

and in the /Users/foo/oracle/instantclient_10_2 directory, I entered

ln -s libclntsh.dylib.10.1 libclntsh.dylib

(otherwise the build script does not find the dynamic library).

IV. Edit setup.py

In my case, I could not run the build script out of the box, because it was complaining that the Oracle version could not be determined. That’s because setup.py is looking for a $ORACLE_HOME/lib directory (or $ORACLE_HOME/bin on a Windows system) and trying to determine the Oracle version by looking for the client libraries it contains. In my case, I don’t have a lib directory, so I patched the setup.py and set the Oracle version by hand.

In your favorite text editor, open /Users/foo/oracle/cx_Oracle-4.3.3/setup.py and replace:

        if self.oracleVersion is None:
            raise DistutilsSetupError, "Oracle home does not refer to an " \
                    "8i, 9i, 10g or 11g installation"

with

        if self.oracleVersion is None:
          self.oracleVersion = "10g"

or whatever your Oracle version is.

V. Build and install

This is just as the README.txt describes:

sudo python setup.py build
sudo python setup.py install

(I got a warning "ld: warning in /Users/foo/Development/oracle/instantclient_10_2/libclntsh.dylib, file is not of required architecture", but I simply ignored it)

I also created a $ORACLE_HOME/network/admin directory and copied the service file our DBA defined (tnsnames.ora) into it in order to make the services known to the Oracle client installation on my Mac. I did a few test queries to verify that it worked as expected.

I have written down my personal setup process for cx_Oracle, because it was somewhat different from Pablo’s approach and I have different OS and software versions. Hopefully, this can be of some help for someone else (or myself, should I ever have to do it again in the future).