Ruby + MySQL dynamic library problems

I wanted to try out Ruby on Rails with MySQL on OS X 10.6. I ran into a few common problems along the way, so I am documenting the process here in case it might be helpful to others.

Step 1: Install MySQL

I grabbed the .tar.gz distribution of the latest MySQL 5.1 release and installed it in a nonstandard location on my computer. “Nonstandard” in this case means “somewhere other than /usr/local/mysql.” This detail would be important in a later step.

Step 2: Install the Ruby mysql gem

I’d installed a 64-bit version of MySQL, so the installation process for the mysql gem was:

sudo env ARCHFLAGS="-arch x86_64" gem install -t mysql \
  -- --with-mysql-config=/path/to/my/mysql/installation/bin/mysql_config

For a 32-bit MySQL installation, replace the “x86_64″ with “x86″ in the ARCHFLAGS.

Step 3: Set the DYLD_LIBRARY_PATH

I omitted this step initially, and when I tried to run “rake db:migrate” for my Rails application, I got an error message:

uninitialized constant MysqlCompat::MysqlRes

In the environment of each user account where you plan to run Ruby apps that depend on MySQL, do this:

export DYLD_LIBRARY_PATH=$DYLD_LIBRARY_PATH:/path/to/my/mysql/installation/lib

Note that most of the command-line tools supplied with binary builds of MySQL appear to be statically linked with libmysqlclient. This means that these tools may work flawlessly even if you’ve neglected to set the DYLD_LIBRARY_PATH. The Ruby mysql gem, however, is dynamically linked to libmysqlclient, so it is essential that the MySQL lib directory be included in your DYLD_LIBRARY_PATH if MySQL is installed in a nonstandard location.

For most other Unix systems, the environment variable to set is LD_LIBRARY_PATH rather than DYLD_LIBRARY_PATH.