MySQL 5.5 on Mac OS X

If you’re (re)building a development workstation on Mac OS X, you may have decided to use the latest MySQL 5.5 packages from Unfortunately, that means you probably have seen (or will soon see) two problems. The first is this:

dlopen(/Library/Ruby/Gems/1.8/gems/mysql2-0.2.6/lib/mysql2/mysql2.bundle, 9): Library not loaded: libmysqlclient.16.dylib
Referenced from: /Library/Ruby/Gems/1.8/gems/mysql2-0.2.6/lib/mysql2/mysql2.bundle
Reason: image not found - /Library/Ruby/Gems/1.8/gems/mysql2-0.2.6/lib/mysql2/mysql2.bundle

That example is from the mysql2 gem, but the same problem exists with the older mysql gem. The problem is that the libmysqlclient shared library in the MySQL 5.5 package does not specify a full path to the library. When something links with it, such as the MySQL gem, it won’t be able to find the library at runtime.

There are two ways to fix this.

  1. The easy way (but see the July 2012 update below): modify DYLD_LIBRARY_PATH in your .bash_profile (or equivalent if you use another shell). The advantage to this method is that it fixes it once for anything that links with the MySQL client libraries going forward. Add:

  2. The hard, do-it-again-someday way: modify the .bundle files within the gem to use an absolute path to the MySQL client library. The fix is lost when reinstalling the gem or updating to a new version and must be reapplied. Change to your gem’s root, somewhere like /Library/Ruby/Gems/1.8/gems/mysql-2.8.1 or .../mysql2-0.2.6, or even both. There are two .bundle files within the gem (under lib and ext) that you must run the following command on.

    $ sudo install_name_tool -change libmysqlclient.16.dylib /usr/local/mysql/lib/libmysqlclient.16.dylib mysql_api.bundle

The second problem with the MySQL 5.5 packages is in the MySQLStartupItem and preference pane. Neither work to start or stop the server.

  1. The ownership of the StartupItem files is wrong. OS X complains with

    “/Library/StartupItems/MySQLCOM” has not been started because it does not have the proper security settings.

    To fix that, run:

    $ sudo chown -R root:wheel /Library/StartupItems/MySQLCOM
  2. basedir and datadir are not set in /usr/local/mysql/support-files/mysql.server, which breaks the preference pane. Edit that file with superuser privileges (sudo mate or vi, joe, …) and set them:


Update July 2012: A change in OS X 10.8 makes the easy method above less elegant. If you set that variable, every time you run a setuid or setgid program, you get this warning on stderr:

dyld: DYLD_ environment variables being ignored because main executable (...) is setuid or setgid

Ruby developers using Phusion Passenger Standalone will see this message displayed in their console every five seconds. It gets really irritating, very fast.

I have filed a bug with Apple. It’s also at OpenRadar.

In the meantime, there is also a third way to fix the client library path problem that doesn’t require setting DYLD_LIBRARY_PATH (working around this 10.8 issue) or hacking .bundle files with install_name_tool:

  1. $ brew install mysql