Common pitfalls when installing the ibm_db gem

Installing the ibm_db gem on Windows is as easy as running gem install ibm_db. Next to no problems have been reported, as the the installation is as smooth as it gets. On Linux things can get a bit trickier though. Having helped dozens of people resolve installation problems, I’ve gathered some insight into what the common pitfalls are when installing the ibm_db gem on *nix systems. Here I’ve put together a checklist, in case you’re experiencing issues with your own install.

First and foremost, the most common error message is a variant of the following:

$ sudo gem install ibm_db
Building native extensions.  This could take a while...
ERROR:  Error installing ibm_db:
	ERROR: Failed to build gem native extension.

/usr/bin/ruby1.8 extconf.rb install ibm_db
checking for SQLConnect() in -ldb2... no
*** extconf.rb failed ***
Could not create Makefile due to some reason, probably lack of
necessary libraries and/or headers.  Check the mkmf.log file for more
details.  You may need configuration options.

Provided configuration options:
	--with-opt-dir
	--without-opt-dir
	--with-opt-include
	--without-opt-include=${opt-dir}/include
	--with-opt-lib
	--without-opt-lib=${opt-dir}/lib
  ...
  ...

The gem fails to install because the SQLConnect() function provided by DB2’s development headers (which are required to build the gem) cannot be found/loaded.

This brings us to our quick checklist:

1. Have you sourced the profile? This is done by running:

. /home/db2inst1/sqllib/db2profile

You may need to replace the dot, with source depending on your shell.

2. Have you specified where DB2’s directory and library are to be found? You can do so by running:

export IBM_DB_DIR=/home/db2inst1/sqllib
export IBM_DB_LIB=/home/db2inst1/sqllib/lib32

3. Did you install the required development headers during the installation? These are available by selecting “Base application development tools” under the section “Application Development Tools” in the DB2 Setup Wizard (having selected a “custom” installation beforehand).

You can double check this by running:

ls /home/db2inst1/sqllib/include

This should show you a series of .h files, including sqlcli1.h. If you don’t see them, then you need to repeat the setup procedure so as to add the development tools. Likewise, you should also see a series of .so files, including
libdb2.so when you run: ls /home/db2inst1/sqllib/lib32.

4. Are you trying to perform the installation when logged in as the db2inst1 user? If you’re doing this, it’s best not to. It doesn’t matter if db2inst1 is a suoder or not. Don’t run sudo gem install ibm_db as the instance user.

5. If nothing else works, try to install as the root user (on certain systems sudo won’t cut it). The following complete procedure works in 99% of cases:

sudo -s
. /home/db2inst1/sqllib/db2profile
export IBM_DB_DIR=/home/db2inst1/sqllib
export IBM_DB_LIB=/home/db2inst1/sqllib/lib32
gem install ibm_db

If this checklist doesn’t help you, then you can reach for the RubyForge forum, where the DB2 on Rails community and the IBM team will be happy to help you.

November 11 2008 | How-to and Tips&Tricks | No Comments »

A major milestone for DB2 on Rails

The IBM API development team has released version 1.0 of the ibm_db gem, which includes both the Ruby driver, and the Rails adapter, for IBM’s databases. This is a very important milestone for the DB2 on Rails community, and it ships with quite a few goodies.

Besides a few bug fixes, this version adds support for DB2’s secure connections via SSL, short-hands to use char, double and xml when using both create_table and change_table in Rails’ new “sexy migrations”, and enables change_column_null to work with DB2.

Even more importantly, it adds support for Transactional Migrations in Rails 2.2. What this means to you is that any DDL changes performed by a migration file before an exception has been raised, will be rolled back by DB2. This is a handy new feature in Rails 2.2, and our gem backed support for it, even before this version of Rails was shipped.

Speaking of Rails 2.2, which is about to be released, you’ll finally be able to run rails my_app -d ibm_db. This will generate a DB2-specific config/database.yml file. This move is possible thanks to a patch that was submitted by IBM to the Rails team. As handy as it is, the great news is not so much in this new feature, but rather in the fact that the Rails team has shown that they’re open to accepting patches that extend features to commercial databases as well, and not only the three open source ones they support. This can open up a world of possibilities for the future of DB2 on Rails, and it will mean less reliance on external plugins.

As usual, install as follows (on *nix systems):

$ . /home/db2inst1/sqllib/db2profile
$ export IBM_DB_DIR=/home/db2inst1/sqllib
$ export IBM_DB_LIB=/home/db2inst1/sqllib/lib
$ sudo gem update
$ sudo gem install ibm_db

On Windows, simply run:

gem install ibm_db

November 08 2008 | Announcements | 20 Comments »