Services Spotlight:

How To Install mysql2 gem on Windows 7

Written By Corlew Solutions
Updated November 17, 2014
Published August 1, 2014
Why Corlew Solutions?

We write great software and provide amazing technical support. Contact us today if you need help with a software project:

  • Website: Send an inquiry
  • Email:
  • Phone: (703) 688-3058

Article Technology Info

This article discusses the following technologies:

  • MySQL - Open Source database software.
    (website | download | docs)
  • mysql2 gem - A gem which binds Ruby to libmysql
    (github)
  • Windows 7 - A popular proprietary operating system from Microsoft.
    (website)

Introduction

If you plan on running Ruby on Rails with MySQL as the database, you will need a gem to facilitate the connection to the database. One of the more popular gems these days is the mysql2 gem and it can be a little tricky to install on Windows 7 because it needs to be compiled using tools which are native to *nix operating systems.

Step 1: MySQL Server and Connector C

First things first. You should have Ruby, MySQL Server and Connector C installed on the system before trying to install the mysql2 gem AND each one of those components must all be 32bit or all 64bit. No mixing and matching unless you want to deal with issues down the line. This section will walk you through getting the latest versions of these softwa

Install MySQL Server and Connector C Together

If you haven’t already installed MySQL Server and Connector C, checkout our article on How to Install MySQL Server 5.6 on Windows 7 Development Machine to get MySQL server installed. While using the installation wizard for MySQL server, you will also have the option to download and install MySQL Connector C.

Install or Upgrade Connector C

If you need to install Connector C or upgrade to the latest version, follow the instructions in this section. Even if you just installed Connector C via the MySQL Server installation wizards, it’s worth checking if a newer version is available because the MySQL Server wizard doesn’t always find the latest version of Connector C.

  • Open Windows Explorer and navigate to C:\Program Files\MySQL or C:\Program Files (x86)\MySQL
  • Look for the MySQL Connector C 6.X.X folder. If it exists, Connector C is already installed. Note the version number which is contained in the folder name.
  • Visit the Connector C downloads page and determine the latest version of Connector C.
  • Download the installer for the 32bit or 64bit version of Connector C from the direct downloads page Connector C downloads page.
  • Run the installer. It will detect if Connector C is already installed and go into Upgrade mode if necessary.
  • If you were upgrading, the installer may not have changed the Connector C folder name to match the new version. Double check this by visiting Connector C folder in the File Explorer again and change the folder name to match the new version if necessary.

Step 2: Prepare Connector C Bug Workround

Important Note: In theory, we should just be able to point the mysql2 gem at the Connector C folder when the mysql2 gem is being built and everything would be great. Unfortunately, there is a bug somewhere between Ruby, mysql2, and Connector C which causes a segmentation fault when using the mysql2 gem. More information about this bug can be found here 1) mysql2 issues 372 discussion, 2) Ruby issue 8591 discussion, and 3) Google Groups Discussion.

Simple Fix

The easiest fix is to download a specially built copy of Connector C and use it when building the mysql2 gem. This solution works great and the only downside is it uses Connector C 6.0.2 64bit, which is now getting a little long in the tooth and may not help folks with a 32bit setup. We use this solution with 64bit Ruby, and 64bit MySQL Server and it works great. At this time, we cannot confirm if it works with a 32bit setup (if you can confirm that it works for 32bit, please let us know so we can update the article).

  • Download a specially compiled version of a compatible Connector C. Location 1 or Location 2
  • Extract the zip file to c:\
  • Rename the folder to mysql64 to make the steps below easier.
  • Verify that the folder C:\mysql64\include exists. If your path looks like C:\mysql64\{something}\include then you need to move the contents in the {something} directly to the same level as the {something} directory and delete {something}.

Advanced Fix

If you would like to use the latest version of Connector C, then you can build your own modified Connector C against any version of Connector C that you like. Instructions for doing so can be found towards the bottom of this page.

Step 3: Install the Ruby DevKit

The mysql2 gem needs to be compiled on Windows 7 during the installation process. This presents a problem for Windows users since the gem expect various *nix tools to be available on the target system. Fortunately, the Ruby DevKit (provided by the RubyInstaller team) takes away all of the pain. Checkout our article on installing the Ruby DevKit for instructions on how to setup the DevKit. It should only take a couple minutes to get the DevKit installed and you will likely need it for other Ruby gems which also require *nix build tools.

Step 4: Install the mysql2 Gem

Now that all the preparation has been done, installing the mysql2 is fairly simple. We’re going to first try and install mysql2 against the standard Connector C code just in case the segmentation fault bug gets fixed in the future.

  • Identify the path to mysql Connector C. For 64bit installations, it probably looks similiar too: C:\Program Files\MySQL\MySQL Connector C 6.1.5
  • Open a command prompt and execute: gem install mysql2 -v=0.3.17 --platform=ruby -- ‘--with-mysql-dir="C:\Program Files\MySQL\MySQL Connector C 6.1.5"’
  • Copy C:\Program Files\MySQL\MySQL Server 5.6\lib\libmysql.dll to C:\Ruby21-x64\bin

Test out the installation by running rake db:create or some other database related command. If you get an error then the bug has not been fixed and you will need to uninstall the mysql2 gem and reinstall using the modified Connector C.

  • Uninstall the mysql2 gem gem uninstall mysql2
  • Reinstall the gem with the special Connector C gem install mysql2 -v=0.3.17 --platform=ruby -- --with-mysql-dir="C:\mysql64"
  • Copy C:\mysql64\lib\libmysql.dll to C:\Ruby21-x64\bin
  • Delete the C:\mysql64 directory.

Now rerun the rake db:create command and life should be good.

We hope you found this article useful. If you see any mistakes, missing features or ways to improve it, please let us know in the comments below so we can update its contents. If you're willing to link to us, we would sincerely appreciate it!

Corlew Solutions is a Web Design and Web Application Development company based in Fairfax Virginia, minutes away Washington D.C. If you're looking for great web design from the Northern Virginia area or web design from the Washington D.C. area we can help. Contact Us today!

comments powered by Disqus