DBD::Oracle is usually a pain to install if you haven’t already done it a gazillion times. After that, it’s just an annoying itch. In this article I’ll cover installing DBD::Oracle using Oracle Instant Client, Ubuntu 9.04, and Perl 5.10. Since we’re using the Instant Client, you’ll need some Oracle DB you can connect to in order to do the testing. You can choose to skip testing altogether, but you might be into a surprise later.

DBI and DBD::Oracle

Installing the DBI is always easy – regardless if you’re running Windows or Linux. Just follow the steps.

1. Get root password if you don’t already have one: sudo passwd root
2. Switch to root: su -
3. Run CPAN: perl -MCPAN -e shell
4. Check if DBI is already installed: m DBI
5. If it’s not installed, install it: install DBI

That should do the trick for the DBI. The DBD::Oracle is a bit more complicated and we’ll just use CPAN to download it for us. The rest is manual.

1. Check for DBD::Oracle: m DBD::Oracle
2. Download it: get DBD::Oracle
3. Exit CPAN: q

Now we should have the DBD::Oracle distribution downloaded to our CPAN build directory. If you don’t know where to find it, look for .cpan dir under your root home or (if you started CPAN for the first time doing sudo from your main user, look for it under your main user’s home directory). We’ll leave that distro aside for a moment and work on the other pre-requisites.

Oracle Instant Client

Download the instant client packages you’ll need. I chose to download the RPMs and convert them to .deb files using alien. Oracle also provides .zip files if you don’t want to do it the alien way.

Oracle Instant Client Download Site i386
Oracle Instant Client Download Site AMD64 32- and 64-bit

Accept the license agreement by clicking the Accept radio button. Since the i386 and amd64 files have different names, check the bold words in the file names to know which ones to download (the names below are for the i386 platform). Also, if you don’t have a user_id for Oracle, you’ll be prompted to register one once you click the link. It’s free of charge.

• oracle-instantclient11.1-basic-xx.x.x.x.x-x.i386.rpm
• oracle-instantclient11.1-sqlplus-xx.x.x.x.x-x.i386.rpm
• oracle-instantclient11.1-devel-xx.x.x.x.x-x.i386.rpm

AMD64 has only zip files from what I could find, and they’re named a bit differently, too (remove the 32 for the 64-bit version:

• instantclient-basic-linuxAMD64-32-xx.x.x.x.x-yyyymmdd.zip
• instantclient-sqlplus-linuxAMD64-32-xx.x.x.x.x-yyyymmdd.zip
• instantclient-sdk-linuxAMD64-32-xx.x.x.x.x-yyyymmdd.zip

Note: Extract the zips into a directory called instantclient and skip to the Set Up your Environment Variables section if you’re using the AMD64 or i386 zip files.

Install alien and libaio

Now is the time to install alien, which is an application that converts rpm files into .deb format to be used with dpkg. Instant Client also requires libaio. Both can be installed through the Synaptic Package Manager. Just open it, look for alien, mark it for install and do the same for libaio and libaio-dev. Once they’re installed, you’re good to move on to install the Instant Client. Just don’t forget to exit Synaptic Package Manager, since we’ll be using dpkg and it won’t work if Synaptic is open.

Install Oracle Instant Client

First step to install Oracle Instant Client from rpm files is to convert them into .deb files. Do that with alien by running the following command (from a command line in the directory where you downloaded your RPMs):

$ sudo alien --scripts *.rpm

It takes a little while to run, so be patient. Once it’s complete, install the newly created .deb files:

$ dpkg -i *.deb

Set up your Environment Variables

The nasty thing about rpm files is that it’s not always easy to know where the files were installed. If you opted for the zip file approach, your install will most definitely be different. For RPM install, add this to your .bashrc file (swap xx.x for your oracle version):


export ORACLE_HOME=/usr/lib/oracle/xx.x/client
export PATH=$PATH:$ORACLE_HOME/bin
export LD_LIBRARY_PATH=$ORACLE_HOME/lib


Update: If you get an ELFCLASS64 error, try setting LD_LIBRARY_PATH to $ORACLE_HOME/lib32 instead.

Reload your .bashrc file:
$. ~/.bashrc

Note: by default, Oracle Instant Client doesn’t come with a tnsnames.ora file or the directory structure where it’s usually found. We’ll have to create that ourselves -

$ mkdir -p $ORACLE_HOME/network/admin; touch $ORACLE_HOME/network/admin/tnsnames.ora

Install DBD::Oracle

It’s time to finally install DBD::Oracle. Go to your CPAN build directory and cd into DBD-Oracle-*. As a user having the environment variable set from the previous section, run Makefile.PL portion.

$ perl Makefile.PL

There’s no need to set INC or LIB with the alien approach, but if you run into any issues, try giving Makefile.PL the path to your include dir for INC, and lib dir for LIB.

Next, run

$ make.

It will raise a few warnings, but unless it exits with an error, you should be OK.

The next logical step is to run make test. However, this will undoubtedly fail unless you have a valid entry in your tnsnames.ora file. If you don’t, you can skip this test and hope that everything works later on. Otherwise, update your tnsnames.ora file with a valid entry, and set one more environment variable before running the test:

$ export ORACLE_USERID="user/passwd@tns_entry_name"
$ make test

This is usually the hardest part to pass with total success. Many things can go wrong. In my case, the valid entry I use doesn’t have full grants to the user I log in as. This always triggers an error on the create/access sequences portion of the testing. I simply ignore it nowadays – make sure you analyze your test results thoroughly before choosing to ignore the errors as well.

Now that the testing is over, simply run
$ make install
as a super user and you’re all set!

Book suggestions:

Here is a list of what I used:

Machine: Sun Solaris SPARC on build and target machines
Oracle: Oracle 10g client (build machine only)
Perl: v. 5.10.0 (build machine only)
Perl modules: DBI (1.607), DBD::Oracle (1.22), PAR (0.983), pp (0.982), PerlIO (1.04) (build machine only)

How I did it:

Being the lazy bastard that I am, I decided to write a Perl module that would do my DBI connections for me once I supplied it the SID, username, and password. This module isn’t in CPAN, but you can probably find similar ones in there. Who knows maybe one day I’ll make it available to the public, but for now I will only explain how it works and show the tidbits I used to get it connecting without the Oracle client installed. Let’s call my module MyDB.pm (at the time of this writing, there is no MyDB.pm module in CPAN).

MyDB.pm: exports one subroutine: connect().  connect() takes an array reference of 3 values: SID, username, password. It then uses the given SID to check against %configured_dbs and fetch hostname/IP,  port, and alternative SID. It then connects to the DBI. Pretty straight-forward.

Oracle Client: You’ll need the Oracle Client installed in your build machine. Or not. As long as you have access to the following files (the example here is for 10.1 version – your filenames may vary): libclntsh.so.10.1, and libnnz10.so. These are the magic libs that we will carry along with us.

PAR/pp: The Perl Archive Tool is a VERY handy module. It basically allows you to pack modules/files into a regular zip (renamed to .par) and even to create self extracting executables. It comes with tools such as parl to load those packages and deploy the scripts inside, or you can run it from inside a separate script to use your modules without having to install them in a specific path. Oh, and with the PAR self extracting executable, you can even bundle Perl core files and run it in a machine that doesn’t have Perl installed! Sweet, eh? pp is part of the PAR family – it’s thescript that does the creation of the par packages. One downside of PAR is that it creates potentially HUGE packages. A simple hello world can be over 2Mb large. But that’s not a concern in this tutorial, since we will be getting rid of having to keep Oracle up to date in every single machine, changing environment variables and the such.

When running a PAR package, it calculates the MD5SUM of the file and creates a temporary directory under /var/tmp/par-userId/cache-md5sum (replace userId with the ID of the person running the file, and md5sum with the actual md5sum) . It then unpacks the contents of the PAR into that directory and sets some environment variables – some of which will tell Perl to check in there for modules.  However, it seems to not automatically extract the libs, so we have to modify MyDB.pm to have it behave appropriately.

Making MyDB.pm work when called in a PAR context

Create a BEGIN block checking for $ENV{PAR_TEMP}. This is the value of the PAR temp directory where the files should be extracted. Since PAR creates zipped files, it offers a method to return an Archive::Zip  handler:

my $zip_handler = PAR::par_handle(‘MyDB.par’);

Now you can use Archive::Zip methods to manipulate your .par file. I used the following code for my BEGIN block:

BEGIN {
	if ($ENV{PAR_TEMP}) {

		# Get $par_cache (easier to type than $ENV{PAR_TEMP})
		my $par_cache = $ENV{PAR_TEMP};

		# Get Zip handler
		my $par_file = PAR::handle("MyDB.par");

		# Set files to look for
		my %membersToFind = (’libclntsh.so.10.1’ =>1,
							 ’libnnz10.so’ => 1 );

		# Unpack files
		for my $m ($par_file->members()) {

			# Get path/name of the zipped file
			my $fileName = $m->fileName();

			# Prepare to check if the libs
			# have already been extracted
			use Find::File;

			# Iterate through %membersToFind keys
			for my $k (keys %membersToFind) {

				# If zipped file is one of the keys...
				if ($fileName =~ /$k/) {

					# do nothing if the file has already been extracted
					next if find(sub { /$k/ or return 0 },$par_cache); 

					# ...then remove from hash (we’ll check the hash later)...
					delete $membersToFind{$k};

					# ... and unpack into $par_cache directory
					$par_file->extractMember($fileName,"$par_cache") ||
					warn ("Failed to extract $fileName n");

				}
			}
		}

		# Check to see if any of the files wasn’t unpacked because it wasn’t found
		if (scalar(keys %membersToFind) > 0) {

			warn("The following file(s) could not be found in PAR file: " .  join(’,’,@{ keys %membersToFind }) ."n");

		}
	}
}

So now MyDB.pm will know what to do if $ENV{PAR_TEMP} is set.  The next step is to generate the PAR file.

Creating the PAR package

You’ll need a dummy perl script to pass to pp:

	$ echo "use MyDB;" > dummy.pl

and then create the PAR file. Make sure MyDB.pm and your oracle libs are in places where Perl can find it. I placed MyDB.pm in the same directory as dummy.pl, and set LD_LIBRARY_PATH to my $ORACLE_HOME/lib32 (if you’re using Instant Client, set it to $ORACLE_HOME/instantclient or wherever your instant client keeps the libs). The pp command is this (on a shell prompt):

$ pp -z 9 -v 3 -p -d -o MyDB.par
	-X DBD::Proxy
	-X DBD::DBM
	-X DBD::File
	-X DBD::NullP
	-X DBD::Gofer
	-X DBD::Sponge
	-X DBD::ExampleP
	-X DBD::mysql
	-X DBD::Gofer::Policy::rush
	-X DBD::Gofer::Policy::classic
	-X DBD::Gofer::Policy::Base
	-X DBD::Gofer::Policy::pedantic
	-X DBD::Gofer::Transport::pipeone
	-X DBD::Gofer::Transport::Base
	-X DBD::Gofer::Transport::stream
	-X DBD::Gofer::Transport::null
	-X DBD::mysql::GetInfo
	-X DBD::Chart
	-X DBD::Chart::Plot
	-M MyDB
	-M PerlIO
	-l libclntsh.so.10.1
	-l libnnz10.so
        -l libociei.so   # for Oracle instant client users only! Thanks to Jonathon Robinson for the heads up. (see comments for details)
	dummy.pl

pp command explained

pp: the PAR packer script
-z 9: maximum compression
-v 3: maximum verbosity
-p: create par file
-d: dependent. This means it will not add the Perl interpreter to the bundle. This reduces its size, but makes it rely on either perl being installed in the target machine, or your script (the one that’s going to use MyDB) being PAR’d without the -d option.
-0 MyDB.par: the filename to be used on output
-X module: removes un-necessary modules. Read more about it here.
-M module: the modules you want to add (PAR sometimes misses a module during its dependency scan).  PerlIO is required.
-l lib: adds the additional libs
dummy.pl: last item of the command, tells pp what the main script is.
There – after lots of output on the screen, you should have a pretty large MyDB.par (at least 7Mb). Now we have to alter our main script (the one that uses MyDB in the first place) to have it handle the PAR file. Add the following lines right after your use strict; line (you DO use strict, RIGHT?!).

          use PAR './MyDB.par';
          use MyDB;
          # the rest is business as usual

Once altered, you can choose to pp your script to have it run without a perl interpreter on another machine. This might take several attempts, since you will have to test the executable a few times to make sure you got all your modules bundled. The basic pp command though is this:

       $ pp -z 9 -v 3 -o yourscript.exe yourscript.pl    # .exe not required

Here the absense of -d makes it assume -B which bundles Perl inside the executable. As mentioned before, you might need to add some -M module parameters before yourscript.pl to catch any missing modules.

Running the scripts

To run the scripts, just send them to the target machine and execute yourscript.exe. It will fetch MyDB.par in the same directory, extract it to $ENV{PAR_TEMP} the first time (so it might be a little slow at first) and carry on with its logic.

Caveat

I strongly advise that you delete your par_cache directory between rebuilds (while testing). The reason for this is that the cache will be created by the execution of yourscript.exe and NOT by MyDB.par. When this happens and you alter MyDB.par, the changes will not be reflected when you run yourscript.exe.

If you liked this post, please leave a comment. If you didn’t, leave a comment too! I’d like to know what people think of my blog and ways to improve it.

Book Suggestions:

This time I got a undefined symbol error. A quick look in Google showed me that Erik Squires had the same exact problem. Lots of searching later, I find that Google can’t find a handy solution anywhere… So I send Erik an email asking about the solution and to my surprise, he answers only 1 (!!) minute after I click send. Talk about a fast reply!!

Hats off to Erik! You will find the solution here: http://cpae.typepad.com/capacity_planning_and_eng/

Hint: the oci.def that he mentions in his post is inside your DBD::Oracle build directory. Don’t get it confused with ocidef.h file in your $ORACLE_HOME/oci/include directory (that’s where I looked first).

I’m adding the error message below with a big SOLUTION header for any Googler out there having the same problem. No need to keep reading if the text above was enough to solve your problem.

Oracle 10g + DBD::Oracle + Cygwin issue

Make error:

————————————————————–

cp Oracle.pm blib/lib/DBD/Oracle.pm
cp oraperl.ph blib/lib/oraperl.ph
cp dbdimp.h blib/arch/auto/DBD/Oracle/dbdimp.h
cp ocitrace.h blib/arch/auto/DBD/Oracle/ocitrace.h
cp Oraperl.pm blib/lib/Oraperl.pm
cp Oracle.h blib/arch/auto/DBD/Oracle/Oracle.h
cp lib/DBD/Oracle/GetInfo.pm blib/lib/DBD/Oracle/GetInfo.pm
cp mk.pm blib/arch/auto/DBD/Oracle/mk.pm
/usr/bin/perl.exe -p -e "s/~DRIVER~/Oracle/g" /usr/lib/perl5/site_perl/
5.10/i686
-cygwin/auto/DBI/Driver.xst > Oracle.xsi
/usr/bin/perl.exe /usr/lib/perl5/5.10/ExtUtils/xsubpp  -typemap /usr/
lib/perl5/5
.10/ExtUtils/typemap -typemap typemap  Oracle.xs > Oracle.xsc && mv
Oracle.xsc O
racle.c
gcc -c  -IC:/oracle/product/10.2.0/client_1/oci/include -IC:/oracle/
product/10.2
.0/client_1/rdbms/demo -I/usr/lib/perl5/site_perl/5.10/i686-cygwin/
auto/DBI -DPE
RL_USE_SAFE_PUTENV -U__STRICT_ANSI__ -fno-strict-aliasing -pipe -I/usr/
local/inc
lude -DUSEIMPORTLIB -O3   -DVERSION="1.22" -DXS_VERSION="1.22"  "-
I/usr/lib/
perl5/5.10/i686-cygwin/CORE"  -Wall -Wno-comment -DUTF8_SUPPORT -
DNEW_OCI_INIT -
DORA_OCI_VERSION="10.2.0.1" Oracle.c
gcc -c  -IC:/oracle/product/10.2.0/client_1/oci/include -IC:/oracle/
product/10.2
.0/client_1/rdbms/demo -I/usr/lib/perl5/site_perl/5.10/i686-cygwin/
auto/DBI -DPE
RL_USE_SAFE_PUTENV -U__STRICT_ANSI__ -fno-strict-aliasing -pipe -I/usr/
local/inc
lude -DUSEIMPORTLIB -O3   -DVERSION="1.22" -DXS_VERSION="1.22"  "-
I/usr/lib/
perl5/5.10/i686-cygwin/CORE"  -Wall -Wno-comment -DUTF8_SUPPORT -
DNEW_OCI_INIT -
DORA_OCI_VERSION="10.2.0.1" dbdimp.c
dbdimp.c: In function `ora_db_login6':
dbdimp.c:450: warning: cast to pointer from integer of different size

{ A bunch more cast and int format warnings from oci8.c}

rm -f blib/arch/auto/DBD/Oracle/Oracle.dll
LD_RUN_PATH="C:/oracle/product/10.2.0/client_1/lib:C:/oracle/product/
10.2.0/clie
nt_1/rdbms/lib" g++  --shared  -Wl,--enable-auto-import -Wl,--export-
all-symbols
 -Wl,--stack,8388608 -Wl,--enable-auto-image-base -L/usr/local/lib
Oracle.o dbdi
mp.o oci8.o  -o blib/arch/auto/DBD/Oracle/Oracle.dll
          /usr/lib/perl5/5.10/i686-cygwin/CORE/libperl.dll.a -L/
cygdrive/c/cpan/
5.10.0/build/DBD-Oracle-1.22 -loci      

Oracle.o:Oracle.c:(.text+0x6ba9): undefined reference to
`_OCILobGetChunkSize'
dbdimp.o:dbdimp.c:(.text+0x10e3): undefined reference to
`_OCINlsCharSetIdToName
'
dbdimp.o:dbdimp.c:(.text+0x110f): undefined reference to
`_OCINlsCharSetIdToName
'
collect2: ld returned 1 exit status
make: *** [blib/arch/auto/DBD/Oracle/Oracle.dll] Error 1

—————————————————————

[ad#middle_end]

!!! HERE IS THE SOLUTION !!!

Taken from http://cpae.typepad.com/capacity_planning_and_eng/

Thanks to Erik Squires!

[Quote]

undefined reference to `_OCILobGetChunkSize’

Several people helped me with a fix, but this text below is thanks to Jerry Reed. Thanks Jerry!

Please note this problem ONLY occurs under Windows. If you are running Perl under Unix/Linux/MacOS you should be fine.

Jerry Wrote:

The make of DBD Oracle builds an intermediate lib, liboci.a. Functions defined in this lib are somehow culled from the appropriate cygwin distro dll by the line that reads:

system(“dlltool –input-def oci.def –output-lib liboci.a”) at line 235 in Makefile.PL.

But oci.def lacks entries for the two undefined symbols -
_OCILobGetChunkSize

and

_OCINlsCharSetIdToName

(the later is named twice in the linker output).

Strip the leading underscore and insert them into a copy of oci.def. (I inserted them in alpha order, but I do not know if this is really required.)

rm, or use make clean to remove liboci.a and cause it to be rebuilt.

perl Makefile.PL
make

You should get no unresolved symbols now. You can check that liboci.a now contains the correct entries by:

nm liboci.a | egrep -i ‘(chunk|nls)’

[/Quote]

[ad#middle_end]