Installing MySQL on Mac OS X

Update: I’ve posted updated instructions for compiling MySQL on Snow Leopard.

What follows are instructions for building and installing MySQL 5 on Mac OS X. These instructions should work perfectly on both Tiger and Leopard.

If you’re a pro at this type of thing already, if you’re impatient, or just feeling lucky, you can download the basic install steps as a shell script and give that a go. Just make sure you’ve installed Xcode and set your path correctly (if that doesn’t make sense, you should keep reading).

Why You Might Want to Build MySQL Yourself

Although there is a MySQL package-installer for Leopard (available here), there are a few reasons why you might still want to compile your own version of MySQL:

  1. You’ll have a stand-alone, easy-to-update version of MySQL that you control and understand
  2. When a new version of MySQL comes out, you won’t have to wait for the MySQL team to release a package for Mac OS X (or for your version of Mac OS X) … just download the latest source and follow the steps – they never change
  3. You can easily uninstall MySQL yourself at any time
  4. Compiling software yourself lets you learn how Mac OS X and the software you use really work behind the scenes

But … there are some downsides, too:

  1. You won’t get a Preference Pane to start/stop MySQL (unless Mantorg agrees to build us one. Idea: email him and tell him you want him to)
  2. It takes about 20 minutes to build and install

In the end, compiling and installing MySQL this way is well worth the effort, as the end result delivers an easy-to-upgrade, system-independent, stand-alone development platform that is impervious to potential problems that can be caused by system updates, operating system upgrades, etc.

By rolling our own from source this way, we also have full control over our environment. We know what’s installed and where, what version we’ve used, where it came from, and there’s no dependence on an external ports system and the breakage or issues that come from relying on others to manage our software.

These issues and additional background information about why one might roll their own tools in this fashion are detailed in the article, Using /usr/local/, which could be considered a prerequisite for this task.

A Quick Warning

While it’s unlikely anything we do here might do any kind of damage to the system, it’s good advice to have a current backup of everything, just in case. I don’t take any responsibility for anything that results from following these instructions. You’re following these instructions at your own risk.

Prerequisites

You’ll need to install Xcode. Xcode can be found in the Optional Installs folder of the installation DVD. You can also download the latest version from Apple by getting a (free) membership from the Apple Developer Connection.

Just double click the Xcode installer package, take the defaults, and you’ll be ready to roll.

A Note About Existing MySQL Installations

If you already have MySQL installed and used the package installer from MySQL to install it, you need to remove a single file (actually a symlink) to disable it:

sudo rm /usr/local/mysql

If you also installed the StartupItem package, you’ll want to remove it as well. Keep in mind that if you ever want to auto-start the old version of MySQL later on, you’ll need to re-download the package installer and reinstall the StartupItem.

sudo rm -rf /Library/StartupItems/MySQLCOM/

Exporting or migrating your old data isn’t difficult, but it is beyond the scope of this article. I may write something up to handle this in a subsequent article if it’s something people want.

Terminal

We’re going to be typing archaic commands into a window using a monospaced font, just like in a movie! And if things go well, later, your life-sized avatar will learn kung-fu.

Open the Terminal application. It can be found in the /Applications/Utilities folder.

Each of the lines below appearing in monospaced type should be entered into Terminal, and be followed by the Return key. But you knew that already.

Setting the Path

Do not skip this step! Most everything else will fail if you do.

Mac OS X, like other UNIX systems, uses something called a path to determine where it should look for applications on the command line (that is, when you’re using the Terminal app). The path is actually an environment variable, set by a special file that’s automatically executed when you open a new Terminal window.

To see if the path has been set properly, we can check the contents of the .bash_login file (the special file hidden in our home folder) for a PATH line using a text editor. TextMate, TextWrangler, BBEdit, and vi are all perfectly good options. To open the file with TextMate, for example, we can type:

mate ~/.bash_login

This will open the file if it already exists, or open a blank file if it doesn’t. Add the following line at the very end of the file:

export PATH="/usr/local/bin:/usr/local/sbin:/usr/local/mysql/bin:$PATH" 

Now save and close the file.

It doesn’t matter how many other lines there are in the file, or what they say or do. Just make sure that this line comes last and you should be fine.

To make sure the changes are picked up correctly, we now need to execute the file with the following command:

. ~/.bash_login

It’s likely there will be no response from the shell here, just the prompt, but that’s OK, the changes have been picked up and we’re ready to move on.

You can also close your Terminal and open a new one instead if you’d like.

Setting Up

I like to create a folder to contain the MySQL source code file and build folder. This way, I can later uninstall MySQL easily, as well as download and compile new versions, all in one place.

For these examples, we’ll create a folder called src in our home folder, and change directories into that folder. It will be our workspace for everything we do here:

mkdir -p ~/src
cd ~/src

You’ll download and compile everything in this new folder.

Download, Extract, Etc.

Now we’re ready to start the real work. Just type (or cut-n-paste) each one of the following lines into Terminal, one by one. When one line finishes (some will take a while and dump a lot of information to the screen), enter the next one.

This will first download and then expand the MySQL source code distribution:

curl -O http://mysql.he.net/Downloads/MySQL-5.1/mysql-5.1.33.tar.gz
tar xzvf mysql-5.1.33.tar.gz
cd mysql-5.1.33

You then need to configure MySQL:

CC=gcc CFLAGS="-O3 -fno-omit-frame-pointer" CXX=gcc 
CXXFLAGS="-O3 -fno-omit-frame-pointer -felide-constructors 
-fno-exceptions -fno-rtti" 
./configure --prefix=/usr/local/mysql 
--with-extra-charsets=complex --enable-thread-safe-client 
--enable-local-infile --enable-shared --with-plugins=innobase

When that process completes, you can initiate the actual compilation process:

make

This part can take a while. Now is a good time to go and get yourself a tasty beverage.

The last part of the build process is where MySQL actually gets installed. You’ll be prompted for your password here, because this is where files actually get written to their actual locations:

sudo make install

Next, we need to setup the initial databases and privileges. You may be prompted for your password again:

cd /usr/local/mysql
sudo ./bin/mysql_install_db --user=mysql
sudo chown -R mysql ./var

That’s it, MySQL is installed. But you’re not done yet.

Auto-Starting MySQL

Now that the install is done, you need to have MySQL auto-start every time you start or reboot your Mac. The easiest way to do this is using launchd.

I’ve prepared a launchd plist file that will manage MySQL, starting it at boot and stopping it cleanly at shutdown. Create a file named com.mysql.mysqld.plist using the text-editor of your choice, and save it to your Desktop. Enter the following text into the file:

<notextile>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"&gt;
&lt;plist version="1.0"&gt;
&lt;dict&gt;
    &lt;key&gt;KeepAlive&lt;/key&gt;
    &lt;true/&gt;
    &lt;key&gt;Label&lt;/key&gt;
    &lt;string&gt;com.mysql.mysqld&lt;/string&gt;
    &lt;key&gt;Program&lt;/key&gt;
    &lt;string&gt;/usr/local/mysql/bin/mysqld_safe&lt;/string&gt;
    &lt;key&gt;RunAtLoad&lt;/key&gt;
    &lt;true/&gt;
    &lt;key&gt;UserName&lt;/key&gt;
    &lt;string&gt;mysql&lt;/string&gt;
    &lt;key&gt;WorkingDirectory&lt;/key&gt;
    &lt;string&gt;/usr/local/mysql&lt;/string&gt;
&lt;/dict&gt;
&lt;/plist&gt;
</notextile>

Now we need to move the file into place and set the permissions on it. You may be prompted for your password again:

sudo mv ~/Desktop/com.mysql.mysqld.plist /Library/LaunchDaemons
sudo chown root /Library/LaunchDaemons/com.mysql.mysqld.plist

With the file in place, the last step is to tell launchd to load and startup MySQL. You may be prompted for your password again:

sudo launchctl load -w /Library/LaunchDaemons/com.mysql.mysqld.plist

If things go well, you won’t see anything special happen, but MySQL will have started up. You can verify this, again back in Terminal:

mysql -uroot

This will initiate MySQL’s command-line monitor. If everything went well, you should see something like this:

Welcome to the MySQL monitor.  Commands end with ; or g.
Your MySQL connection id is 1
Server version: 5.0.45 Source distribution
Type 'help;' or 'h' for help. Type 'c' to clear the buffer.
mysql&amp;gt;

If you see that, that’s it, you’re done! Type exit to quit the MySQL monitor.

If you see something else, verify that your paths are set correctly and try the command again. If things still don’t work, it’s likely that something didn’t work and the compile didn’t finish. Try going through the steps once more and see if you can catch any error messages.

Starting and Stopping MySQL Manually

If you ever want to stop MySQL manually, use this command in Terminal, entering you password when prompted:

sudo launchctl unload -w /Library/LaunchDaemons/com.mysql.mysqld.plist

To start it manually, use this command in Terminal, entering you password when prompted:

sudo launchctl load -w /Library/LaunchDaemons/com.mysql.mysqld.plist

A Note about Security

The easiest way to secure your MySQL installation without affecting the way you (or your applications) will need to communicate with it is to limit anything but local connections to your MySQL server. In other words, only you and the apps you run on your own Mac will be able to connect. You won’t need to enter passwords when interacting with MySQL locally, and won’t need to tweak the default database.yml files that Rails creates, for example.

We can limit access by creating (or editing) the /etc/my.cnf file. If you have TextMate installed, you can enter the following command to create (or edit) the file:

mate /etc/my.cnf

If you use BBEdit, you’d use this command:

bbedit /etc/my.cnf

The handy bit about using TextMate (or BBEdit) for this task is that it will handle authentication and setting permissions for you.

Enter the following text into the file save it and close it, authenticating as needed:

[mysqld]
bind-address = 127.0.0.1

Thanks to my friend Mike Clark for this tip.

If limiting access isn’t enough for you, you can read about setting a root access password for MySQL in this article.

Baking-In the MySQL Bindings

You can gain some bigtime Rails-to-MySQL speed improvements by building the MySQL C bindings for Ruby.

If you have an Intel Mac, just run the following command (entering your password when prompted):

sudo env ARCHFLAGS="-arch i386" gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

If you have a PPC Mac (I hear some still exist), you’d enter:

sudo env ARCHFLAGS="-arch ppc" gem install mysql -- --with-mysql-config=/usr/local/mysql/bin/mysql_config

You’ll see a prompt asking you which gem to install:

Select which gem to install for your platform (universal-darwin9.0)
 1. mysql 2.7.3 (mswin32)
 2. mysql 2.7.1 (mswin32)
 3. mysql 2.7 (ruby)
 4. mysql 2.6 (ruby)
 5. Skip this gem
 6. Cancel installation

Pick the option closest to the top that ends in “(ruby)”. In the example above, we’d want to select option 3.

Uninstalling MySQL

In case you one day decide that you’d like to remove MySQL, it’s easy to do when building from source:

cd ~/src/mysql-5.0.45
sudo make uninstall
sudo launchctl unload -w /Library/LaunchDaemons/com.mysql.mysqld.plist
sudo rm /Library/LaunchDaemons/com.mysql.mysqld.plist

That’s It

So, you’re done. What are you waiting for? Go create the next Google or something.

Special thanks to Koz, Mike Clark, Ryan Schwartz, and Jason Seifer for their tips and suggestions.

More articles in the Archive →