MySQL Forums
Forum List  »  Ruby

Comprehensive Instructions (?) : CORRECTLY Installing AND MAINTAINING mysql Ruby Gem installations ON ANY SYSTEM
Posted by: mike montagne
Date: March 21, 2010 12:01PM


For lack of comprehensive instructions, many people are wasting countless hours trying to install Ruby MySQL Gems, for problems which may in fact relate to any gem distribution. Largely, the difficulties which developers are experiencing relate to the particular directory structure of their Ruby, Rails, and mysql gem RoR distributions, and to ri and RDoc resources, which may or may not have been bundled with their MySQL Ruby Gem distribution.

Hopefully, the following instructions/process will resolve these issues for you, and result in a clean install, first or second try: they pertain to *resolving* how to install present generations of Ruby mysql gems on potentially *any* system.

Why two tries?

As you proceed to install your particular mysql gem distribution, you probably don't know whether your particular mysql gem distribution has been bundled with the ri and RDoc components which the install process may or may not be looking for. Anticipating that these resources are there (because if they are there, they are useful), you first determine the layout of your system (where your mysql gem resources are stored, and where mysql_config resides on your system). You need to determine these two things to install your mysql gem from terminal, by changing to the directory in which the mysql gem resources reside (cd [GemFolder]), then issuing an install gem command which instructs the mysql gem build to know how to interact with your MySQL installation by way of the MySQL installation's mysql_config file. In other words, the install instruction must pass the location of mysql_config to the build process, so your mysql gem will know how to interact with your MySQL installation.

Note that these requisites also compel us to understand that different vintages of mysql gems, mysql gem installations, and MySQL engine installations will require uninstalling and re-installing your mysql gem by the following instructions, so that your mysql gem will know how to interact with yet another MySQL installation. Particularly where MySQL installation protocols accommodate installation reversions, most certainly you will have to re-install your mysql gem at every MySQL engine update, so that it will successfully interact with the new installation's mysql_config, which will inherently be located on a different different directory branch, which your gem has no power to intuit. Of course, your gem may simply *happen* nonetheless to continue working across such upgrades if your subsequent MySQL engine is configured just as the previous was ― if only because values found in the wrong mysql_config happen to rightly equate with the new configuration. Change or remove the previous MySQL installation however; your gem is suddenly dysfunctional; and, unless you understand the issues addressed by this installation procedure, you may spend days trying to figure out what went wrong. Likewise, assuming a simple "gem install mysql" instruction is going to work on the vast system layouts out there will lead you on an endless chase which will never get the job done right unless you follow this simple procedure.

So, we locate two things on our system, which prepare us for two installation tries. We find our gem so that we can cd to the gem directory for our gem build. And we find the path to our mysql_config file, so that we can pass this in two possible build ("install") instructions. The reason for the two possible tries is simply that you probably won't know whether your gem is bundled with ri and RDoc.

Basically then, our first installation try (A) should successfully install your mysql gem *if* it is bundled with the conventional ri and RDoc resources. If the first install attempt (according to these instructions) discovers the ri or RDoc resources have not been bundled with your mysql gem distribution, a second attempt with either or both the following "--no-rdoc" and "--no-ri" switches (B) should succeed in installing your mysql gem without the many "No definition for [ResourceName]" warnings/errors.


There are many people posting that reversion to earlier installations of MySQL solves their issues. Well, indeed, *it is possible* this may restore operation, but only by depriving yourself of a successful installation of your mysql gem. Although I cannot say with due authority, I expect that on the contrary, reversion to an earlier version of MySQL only *happens* to coincide with the directory structure (path to mysql_config) which their particular (incoherent) mysql gem installation had expected. In other words, this is not the fix for the problem; it only happens that probably only in some cases (and particularly *not* where MySQL has been installed differently), this restores a path to mysql_config which happens to enable the mysql gem to communicate with *that* particular MySQL installation. What we are resolving by these instructions in fact, is how to provide the mysql gem with the vital path to mysql_config, upon which it relies to communicate with *any* particular MySQL installation. Of course, another likely coincidence of misunderstanding that an earlier MySQL installation will *happen* to resolve what is only a simple path issue is, that if you installed the gem to work with a previous MySQL installation, the mysql gem's mysql_config path may simply relate to *that* installation only (for instance, it may be looking for mysql_config down a path which includes a MySQL.19.79 directory!): thus the existing mysql gem installation simply works with the previous version of MySQL because the mysql_config of the mysql gem installation relates to that MySQL installation. So, not only is the MySQL version not the issue at all; reversion to an earlier MySQL version does not guarantee you will restore to your mysql gem installation, a path by which it can communicate by way of mysql_config. As the following instructions resolve the mysql_config for the latest MySQL builds, indeed, they resolve the path to mysql_config issue which your mysql gem relies on -- even of course for the most recent vintages of MySQL.

(Note however, that should *the conventions* of these installation issues change in the future (since March 21, 2010), it is certainly possible *then* that these instructions will no longer apply.)


OSX Leopard 10.6.2
ruby 1.8.7 (2008-08-11 patchlevel 72) [universal-darwin10.0]
Rails 2.3.5
mysql (2.8.1) [gem version]
MySQL Server 5.1.44


Presently, some gem install mysql processes at least, compile the gem on the local system. It is possible the compilation will fail if, before you issue the gem install mysql instruction, you don't first cd in terminal to your mysql gem distribution directory. Although I can anticipate why compiles might not need to be performed on Windows systems; as I cannot tell you, I would consider cd-ing to the mysql gem distribution directory an advisable precaution.

Because of the different possible locations of mysql_config, and because we have to tell the gem installation where mysql_config resides, so that the installed gem can communicate with your MySQL installation, *the necessary installation instruction therefore is likely more complicated* than the typical instruction to issue "gem install mysql" from the command line. This is why this simple instruction will not work; and why the following instructions resolve the involved issues.


So, we have to determine two things before we can do this right (P.1, P.2):

P.1) We have to find the directory in which our gem resources are stored, so we can cd to that directory for our build/install process:

On my system, the path to the folder containing the mysql gem ([GemFolder]) is:

This path can vary greatly as a consequence of distribution. You might find your gem folder path from terminal by searching for gems, mysql-, etc.:

sudo find / -name "mysql-" -print

P.2) We have to find the location of mysql_config on our system, so we can pass the installation process the right instruction for the build:

On my system, the path to mysql_config ([mysql_configPath]) is:

To locate mysql_config on my system, I logged in with root privileges and did:
find / -name "mysql_config" -print
sudo find / -name "mysql_config" -print

P.3) If we have a bad install (and each time an install goes awry), we also have to uninstall our gem from terminal:

sudo gem uninstall mysql
gem uninstall mysql

Verify successful results of this process with:
gem list
There should be no mysql gem listed.


Ri and RDoc provide design-time documentation. Support for their intended functions may be missing from a particular mysql gem's compile resources. Our first attempt to install (A) thus presumes these resources are there.

If either of these resources are missing (or not correctly integrated?), our first attempt to install (A) will engender a multitude of "No definition for [ResourceName]" warnings/errors. If we get these warnings/errors, (B) we uninstall the gem (gem uninstall mysql), and we revise our install command parameters to include either or both of the following --no-rdoc and --no-ri switches.


sudo gem uninstall mysql
gem uninstall mysql

Verify successful results of this process with:
gem list
There should be no mysql gem listed.


cd [GemFolder]
...on my system, this translates to:
cd /Library/Ruby/Gems/1.8/gems/mysql-2.8.1


sudo gem install mysql -- --with-mysql-config=[mysql_configPath]
...on my system, this translates to:
sudo gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

* Note that OSX Leopard and other systems will also require your build to set archflags:
sudo env ARCHFLAGS="-arch x86_64" gem install mysql -- --with-mysql-config=[mysql_configPath]
sudo env ARCHFLAGS="-arch x86_64" gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config
(The latter fails on my OSX L system, with the reported "No definition for [ResourceName]" errors on my system.)

* Other UNIX/LINUX systems may require passing Archflag instructions as well. They pertain to the system architecture the build is compiled for. You'll have to look them up for your system. Once you do, they should remain consistent for later builds *on that system* for further re-installs or installs of MySQL Ruby gems.

The build will take a while, so be patient; keep your fingers off the keyboard. When the process is finished, it will report its success. If there are no warnings or errors, you should be fine. If on the other hand, there are a multitude of "No definition for [ResourceName]" warnings/errors, resort to plan B.


sudo gem uninstall mysql
gem uninstall mysql

Verify successful results of this process with:
gem list
There should be no mysql gem listed.

Then, install with the following syntax, including either or both --no-rdoc and --no-ri switches, depending on what were reported not to have definitions. According to most reports, both are usually missing -- for which case, the following commands should succeed as they are:

sudo gem install mysql --no-rdoc --no-ri -- --with-mysql-config=[mysql_configPath]
sudo gem install mysql --no-rdoc --no-ri -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

* Again, with the archflags required for my OSX Leopard system:
sudo env ARCHFLAGS="-arch x86_64" gem install mysql --no-rdoc --no-ri -- --with-mysql-config=[mysql_configPath]
sudo env ARCHFLAGS="-arch x86_64" gem install mysql --no-rdoc --no-ri -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

There is one space between each of these terms, all on one line. Of course, the --no-rdoc and --no-ri switches relieve the compiler/installer of what they can't do. Documentation I found indicated that the .html documentation is usually preferable to the ri and RDoc design time resources. You will probably find this .html documentation in your gem folder. You might copy these folders to wherever you keep your development resources, for handy reference.

If all this works, there should be absolutely no errors in your install process. I was able to "successfully install" by other procedures, but found my development environment dysfunctional in critical respects. For instance, when I went to build my first project with "rails [projectname] -d mysql", even the comment in database.yml instructed to perform an install which did not work because of the path aberration: this resulted in inability to migrate database schemas. In any case, I would say to settle for nothing less than an error and warning free build. I imagine that will save a lot of headache down the road.

So what you're looking for here is not a universal, "right instruction" to install the mysql gem; what we need is universal instruction to build the right instruction for our particular gem and MySQL installation.


mike montagne

Edited 6 time(s). Last edit at 03/24/2010 09:53AM by mike montagne.

Options: ReplyQuote

Sorry, you can't reply to this topic. It has been closed.

Content reproduced on this site is the property of the respective copyright holders. It is not reviewed in advance by Oracle and does not necessarily represent the opinion of Oracle or any other party.