DEV_MEM.dump_to(:blog)

Recently I reinstalled by entire Windows installation due a SSD migration and wanted to take the opportunity to document the configuration process, specially in the light of the known issues with making it work with Ruby.

It is important to mention that most of these issues in Ruby land are generated due the lack of documentation associated on how to properly install MySQL and its related dependencies.

Most of us expect things to Just Work, and we often compare the installation process to installing to Linux or OSX which works out of the box.

What is not mentioned in the documentation installation is that development tools (a compiler) and specific headers and libraries are required. Unless you’ve already installed them, these development artifacts are usually missing from a Windows computer.

What I’m going to describe next is how I installed and configured my environment and how I made it work properly. YMMV if you decided to use different versions of the components I used for this.

Let’s get started:

Download the right version of MySQL

As I mentioned before, I’m using a 64bits version of Windows, so I think it will be best if I download a matching bits version.

So went ahead and visited MySQL download site:

http://dev.mysql.com/downloads/mysql

And selected MySQL Community Server 5.5.13.

From the versions offered, downloaded Windows (x86, 64-bit), MSI Installer

Install MySQL

Invoked the installer and presented with the normal installation wizard.

You can follow the next sequence of images to use my same settings.

Is good to always install your Data files outside the default program installation directory, that way, you can safely upgrade your installation and not to worry about an installer removing your data files.

Ok, so let’s move to the next thing…

Before installing MySQL/Ruby bindings

In order to use my brand new MySQL installation, now I need to install the MySQL bindings for it.

But, there is a small detail: Ruby is 32bits and my MySQL is 64bits, this means I can’t use MySQL provided libraries from Ruby.

Bummer! You told me to install the 64bits version!

Don’t despair! MySQL Connector to the rescue!

That is right, MySQL has something called Connector, the purpose of that library is to avoid a complete MySQL installation when you just need to connect to a remote one.

It comes in different flavors, we are interested in C language support, since that is the language Ruby uses for it’s extensions.

We are going to download a 32bits connector and use it!

So, at my web browser again, decided to visit the MySQL Connector/C download page:

http://dev.mysql.com/downloads/connector/c/

Since I’m not interested in installing this Connector and pollute my clean 64bits installation, I’m going to download the non-installer version.

I scrolled down the listing until I saw the noinstall 32bits version:

mysql-connector-c-noinstall-6.0.2-win32.zip

Decided to extract it to the root of my disk, so I ended with a folder named mysql-connector-c-noinstall-6.0.2-win32 in there.

Remember: extract into a folder without spaces. The same goes for your Ruby installation and the DevKit installation.

Time to install MySQL/Ruby bindings

So, now that all MySQL prerequisites are in place, will open a new command prompt and prepare to install the gem.

This time I’m going to use Ruby 1.9.2, properly installed and configured with the complementary Development Kit (DevKit) which is provided at RubyInstaller website (In case you haven’t installed yet, don’t forget to follow the installation instructions in the wiki)

OK, so in a Command Prompt, will type the gem installation command:

gem install mysql --platform=ruby -- --with-mysql-dir=C:/mysql-connector-c-noinstall-6.0.2-win32

Note the use of forward slashes for the directory where MySQL Connector/C was extracted.

The above command contains two special things:

First, we are telling RubyGems that we want the ruby platform of mysql gem. This particular platform is the one that contains the source code and this will allow us to skip the pre-compiled version of the gem.

The second part, which is added after two dashes, are the additional arguments that we are giving to the gem configuration process to locate our MySQL headers and libraries for successful compilation.

As result of this command, you will see something like this:

Fetching: mysql-2.8.1.gem (100%)
Temporarily enhancing PATH to include DevKit...
Building native extensions.  This could take a while...
Successfully installed mysql-2.8.1
1 gem installed

Which indicates the gem installed successfully.

In case you obtained a different result, please refer to RubyInstaller Troubleshooting page:

https://github.com/oneclick/rubyinstaller/wiki/Troubleshooting

And try the proposed solutions there.

Using the bindings

Now that we installed the gem, we can remove the connector folder we first extracted. Before do that, first we need to take out a file from there: libmysql.dll. This file is required by the gem we compiled and needs to be available for it.

You can find it inside the lib directory of MySQL Connector.

I personally recommend you place it along your Ruby installation, inside the bin directory.

If you have multiple Ruby installations and you use Pik to change between them, you can place the library in the same directory Pik is installed. You need to remember that it is important the libmysql.dll file is on the PATH when you need to use it.

OK, after all that big red warning, let’s test this thing on a IRB console:

irb> require "rubygems"
irb> require "mysql"
irb> conn = Mysql.connect "localhost", "root", "abc123"
irb> result = conn.query "SELECT 1"
irb> result.num_rows
=> 1
irb> result.fetch_row
=> ["1"]
irb> result.free
irb> conn.close
irb> exit

Great!, now you have not just a working MySQL installation but also Ruby configured to talk to it!

Hope you enjoyed this post as I did enjoy creating it. Hope this ease your path on using MySQL with Ruby on Windows.