Simple Oracle Instant Client Installation on Debian Linux

Introduction

I’ve found that the documentation for getting this working is lacking, probably because not all that many people have to do it. Most related links would lead you to believe the process involves Makefile hacks, library shuffling, and any number of difficult-for-the-next-guy-to-reproduce (might be you!) steps. My main goal in writing this is to make it as simple as possible, but no simpler. Additionally, I’d like as much as possible to explain why I chose to do something along with how I chose to do it.

As the post title implies, this is Debian-specific, though I’ve used several other distributions and I see no reason why this post can’t be fairly simply adapted to them. Leave me a comment if these instructions are useful to you and especially if you were able to get it working with another distribution.

What You’ll Need

The Oracle Instant Client is distributed here as a binary package. Navigate to the Platform Downloads section and pick out your architecture. I used the Basic Lite because I do not need translations, but you could just as easily use the Basic package if you do. You will also need the SDK package if you want anything else to be able to use the Instant Client. I do, because I want to set up Perl and PHP to use the Instant Client. Additionally, I need the SQL*Plus package to do simple administrative tasks for our department such as password changes. This may not be something you need. If not, you can safely leave it out. Download the RPMs, and you’re on your way.

One neat trick if you’re like me and don’t want to set up an Oracle account is to use a service called BugMeNot to use an account that someone else has set up. profile.oracle.com seems to have the accounts that worked for me. If you like the service, don’t ruin it for everyone else by doing stupid things with the account. If you want to create an account, you can easily do that instead.

Installation

Now that you have the RPMs you need, we’ll convert them into packages that Debian can use. This will make it easier to do package management. Use a utility called alien to convert the RPMs into .deb packages that you can then install using dpkg. If you don’t have alien, apt-get install alien.


# Replace the filename with the RPM you want to convert.
# You can specify multiple RPMs with one command if you have them.
alien oracle-instantclient-foo.rpm


Now that you have the packages:


# Do this for all of your packages.
dpkg -i oracle-instantclient-foo.deb


and now they’re installed!

Configuration

The next step is to configure Oracle’s tnsnames.ora, which tells Oracle a little bit about the database(s) you’ll be connecting to. This will be site-specific. Before I go any farther, I’d like to define something I’ll use from here on out: ORACLE_HOME. This allows me to refer to that, wherever it may be on your system. By default, my Debian systems (both Etch and Lenny) put the Instant Client in /usr/lib/oracle/{version}/client (64-bit systems will have client64 instead of client). Anywhere you see this in my post, replace ORACLE_HOME with your local path to the Instant Client. That said, you will now put your tnsnames.ora file into ORACLE_HOME/network/admin/tnsnames.ora. Ask your local DBA for help with this part if you don’t know what I’m talking about.

Essentially, you’re done with the required parts! Easy, wasn’t it? Now, if you want SQL*Plus to work, you’ll probably need to tell the linker where to find the Oracle libraries, since they aren’t on the linker path by default. On a Debian system, the linker looks in /etc/ld.so.conf.d for files that it can source. To make my local changes easy to reproduce, I made a new file called oracle.conf and placed it in /etc/ld.so.conf.d. All this file contains is:


ORACLE_HOME/lib


Then, run ldconfig with no arguments to get the linker to source the files, and you’re set. Now, you’re ready to test it! Simply type


ORACLE_HOME/bin/sqlplus


and you should be able to go about your normal Oracle administration. Have fun!

When I tried this for the first time, I got some complaints about libaio. If you see similar complaints after trying to run sqlplus, try:


apt-get install libaio1


to install the asynchronous I/O libraries.

Finishing Touches

The Oracle Instant Client is an interesting beast since it requires an ORACLE_HOME environment variable to operate. My database connection libraries inject that appropriate environment variable when an Oracle database is connected to. If you don’t do something like this, your connections will fail. Optionally, you can do other things such as add this to Apache’s environment so it will always be available, or you can place this environment variable in the environment of users that run certain scripts.

Optional: PHP Integration

We’ll be installing the OCI8 module for PHP. You’ll need to make yourself root for this. You’ll also need to have installed the SDK mentioned earlier, and probably have gcc and make installed.


cd /usr/local/src
pecl download oci8
zcat oci8-version.numbers.here.tgz | tar xvf -
cd oci8-version.numbers.here
# For the phpize step, you might have to install php5-dev
# if it doesn't already exist.
phpize
# Remember, replace ORACLE_HOME with your ORACLE_HOME!
./configure --with-oci8=instantclient,ORACLE_HOME/lib
make
make install


Next, you’ll need to make sure your newly installed PHP module gets loaded when Apache starts up. You do this by adding a file to /etc/php5/conf.d called oci8.ini (or anything, really) and make sure it contains the line:


extension=oci8.so


Restart Apache and you should be good to go.

Optional: Perl Integration

You’ll need to make yourself root. You might also need the gcc and make packages if you don’t have them already on your system. To reduce confusion because of the literal ORACLE_HOME environment variable, I’m using the more generic path. The ORACLE_HOME that follows is literally the environment variable you need to set.


# The following two lines are needed by the installer so that it builds
# the module against the correct Oracle libraries. This is also useful
# if you need to build the module against different versions.
# Remember to replace {version} with the version you want to
# build against.
export ORACLE_HOME=/usr/lib/oracle/{version}/client
export LD_LIBRARY_PATH=${ORACLE_HOME}/lib
# The following line does the same thing as a normal CPAN install
# (e.g. cpan DBD::Oracle) except it does not require the tests to
# pass, because they won't pass (the database credentials the
# test uses are always invalid). Check the output of the test runner
# though, because you want the first test (loading the module) to
# pass, even if the rest fail.
perl -MCPAN -e "CPAN::Shell->force(qw(install DBD::Oracle));"


Conclusion

This should get you well on your way. If any of this looks confusing, it’s probably just because I wrote a lot. Setting up everything described in this post can only take 5-10 minutes if executed reasonably quickly.

Please leave comments if this was helpful to you or if you have places where I can explain myself better or am just flat out wrong. Good luck!