MySQL and OS X

Abstract

This is the MySQL OS X extract from the MySQL 5.1 Reference Manual.

For legal information, see the Legal Notices.

For help with using MySQL, please visit either the MySQL Forums or MySQL Mailing Lists, where you can discuss your issues with other MySQL users.

For additional documentation on MySQL products, including translations of the documentation into other languages, and downloadable versions in variety of formats, including HTML and PDF formats, see the MySQL Documentation Library.

Licensing information—MySQL 5.1.  This product may include third-party software, used under license. If you are using a Commercial release of MySQL 5.1, see this document for licensing information, including licensing information relating to third-party software that may be included in this Commercial release. If you are using a Community release of MySQL 5.1, see this document for licensing information, including licensing information relating to third-party software that may be included in this Community release.

Licensing information—MySQL Cluster.  This product may include third-party software, used under license. If you are using a Commercial release of MySQL Cluster, see this document for licensing information, including licensing information relating to third-party software that may be included in this Commercial release. If you are using a Community release of MySQL Cluster, see this document for licensing information, including licensing information relating to third-party software that may be included in this Community release.

Document generated on: 2016-08-04 (revision: 48440)

Preface and Legal Notices

This is the MySQL OS X extract from the MySQL 5.1 Reference Manual.

Legal Notices

Copyright © 1997, 2016, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

This documentation is NOT distributed under a GPL license. Use of this documentation is subject to the following terms:

You may create a printed copy of this documentation solely for your own personal use. Conversion to other formats is allowed as long as the actual content is not altered or edited in any way. You shall not publish or distribute this documentation in any form or on any media, except if you distribute the documentation in a manner similar to how Oracle disseminates it (that is, electronically for download on a Web site with the software) or on a CD-ROM or similar medium, provided however that the documentation is disseminated together with the software on the same medium. Any other use, such as any dissemination of printed copies or use of this documentation, in whole or in part, in another publication, requires the prior written consent from an authorized representative of Oracle. Oracle and/or its affiliates reserve any and all rights to this documentation not expressly granted above.

Chapter 1 Installing MySQL on OS X

For a list of OS X versions that the MySQL server supports, see http://www.mysql.com/support/supportedplatforms/database.html.

MySQL for OS X is available in a number of different forms:

Native Package Installer format, which uses the native OS X installer (DMG) to walk you through the installation of MySQL. For more information, see Chapter 2, Installing MySQL on OS X Using Native Packages. You can use the package installer with OS X 10.6 and later, and the package is available for both 32-bit and 64-bit architectures. The user you use to perform the installation must have administrator privileges.

Tar package format, which uses a file packaged using the Unix tar and gzip commands. To use this method, you will need to open a Terminal window. You do not need administrator privileges using this method, as you can install the MySQL server anywhere using this method. For more information on using this method, you can use the generic instructions for using a tarball, Installing MySQL on Unix/Linux Using Generic Binaries.You can use the package installer with OS X 10.6 and later, and available for both 32-bit and 64-bit architectures.

In addition to the core installation, the Package Installer also includes Chapter 4, Installing the MySQL Startup Item and Chapter 5, Installing and Using the MySQL Preference Pane, both of which simplify the management of your installation.

OS X server includes a version of MySQL as standard. If you want to use a more recent version than that supplied with the OS X server release, you can make use of the package or tar formats. For more information on using the MySQL bundled with OS X, see Chapter 6, Using the Bundled MySQL on OS X Server.

For additional information on using MySQL on OS X, see Chapter 7, General Notes on Installing MySQL on OS X.

Chapter 2 Installing MySQL on OS X Using Native Packages

The package is located inside a disk image (.dmg) file that you first need to mount by double-clicking its icon in the Finder. It should then mount the image and display its contents.

Note

Before proceeding with the installation, be sure to stop all running MySQL server instances by using either the MySQL Manager Application (on OS X Server) or mysqladmin shutdown on the command line.

When installing from the package version, you should also install the MySQL Preference Pane, which will enable you to control the startup and execution of your MySQL server from System Preferences. For more information, see Chapter 5, Installing and Using the MySQL Preference Pane.

When installing using the package installer, the files are installed into a directory within /usr/local matching the name of the installation version and platform. For example, the installer file mysql-5.1-osx10.6-x86_64.dmg installs MySQL into /usr/local/mysql-5.1-osx10.6-x86_64/ . The following table shows the layout of the installation directory.

Table 2.1 MySQL Installation Layout on OS X

Directory | Contents of Directory
bin, scripts | mysqld server, client and utility programs
data | Log files, databases
docs | Helper documents, like the Release Notes and build information
include | Include (header) files
lib | Libraries
man | Unix manual pages
mysql-test | MySQL test suite
share | Miscellaneous support files, including error messages, sample configuration files, SQL for database installation
sql-bench | Benchmarks
support-files | Scripts and sample configuration files
/tmp/mysql.sock | Location of the MySQL Unix socket

During the package installer process, a symbolic link from /usr/local/mysql to the version/platform specific directory created during installation will be created automatically.

Download and open the MySQL package installer, which is provided on a disk image (.dmg) that includes the main MySQL installation package, the MySQLStartupItem.pkg installation package, and the MySQL.prefPane. Double-click the disk image to open it.

Figure 2.1 MySQL Package Installer: DMG Contents

Double-click the MySQL installer package. It will be named according to the version of MySQL you have downloaded. For example, if you have downloaded MySQL server 5.1.73, double-click mysql-5.1.73-osx-10.6-x86_64.pkg.

You will be presented with the opening installer dialog. Click Continue to begin installation.

Figure 2.2 MySQL Package Installer: Introduction

A copy of the installation instructions and other important information relevant to this installation are displayed. Click Continue .

If you have downloaded the community version of MySQL, you will be shown a copy of the relevant GNU General Public License. Click Continue .

Select the drive you want to use to install the MySQL Startup Item. The drive must have a valid, bootable, OS X operating system installed. Click Continue.

Figure 2.3 MySQL Package Installer: Choose your Hard drive

You will be asked to confirm the details of the installation, including the space required for the installation. To change the drive on which the MySQL server is installed, click either Go Back or Change Install Location.... To install the MySQL server, click Install.

Once the installation has been completed successfully, you will be shown an Install Succeeded message.

For convenience, you may also want to install the startup item and preference pane. See Chapter 4, Installing the MySQL Startup Item, and Chapter 5, Installing and Using the MySQL Preference Pane.

Chapter 3 Installing a MySQL Launch Daemon

OS X uses launch daemons to automatically start, stop, and manage processes and applications such as MySQL. Using launch daemons is recommended over startup items on OS X.

Note

OS X 10.4 deprecated startup items in favor of launchd daemons, and as of OS X 10.10 (Yosemite), startup items do not function. For these reasons, using launchd daemons is preferred over startup items.

Here is an example launchd file that starts MySQL:

<?xml version="1.0" encoding="UTF-8"?>
<plist version="1.0">
  <dict>
    <key>KeepAlive</key>
    <true/>
    <key>Label</key>
    <string>com.mysql.mysqld</string>
    <key>ProgramArguments</key>
    <array>
    <string>/usr/local/mysql/bin/mysqld_safe</string>
    <string>--user=mysql</string>
    </array>
  </dict>
</plist>

Note

Some users report that adding a plist DOCTYPE declaration causes the launchd operation to fail, despite it passing the lint check. For this reason, we have removed it from the example above.

Adjust the ProgramArguments array according to your system, as for example your path to mysqld_safe might be different. After making the proper adjustments, do the following:

Save the XML as a file named /Library/LaunchDaemons/com.mysql.mysql.plist

Adjust the file permissions using the Apple recommended owner "root", owning group "wheel", and file permissions "644"

shell> sudo chown root:wheel /Library/LaunchDaemons/com.mysql.mysql.plist
shell> sudo chmod 644 /Library/LaunchDaemons/com.mysql.mysql.plist

Enable this new MySQL service

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

The MySQL daemon is now running, and automatically starts when your system is rebooted.

Chapter 4 Installing the MySQL Startup Item

The MySQL Installation Package includes a startup item that can be used to automatically start and stop MySQL.

Important

Startup items are deprecated in favor of launchd daemons. For additional information, see Chapter 3, Installing a MySQL Launch Daemon.

To install the MySQL Startup Item:

Download and open the MySQL package installer, which is provided on a disk image (.dmg) that includes the main MySQL installation package, the MySQLStartupItem.pkg installation package, and the MySQL.prefPane. Double-click the disk image to open it.

Figure 4.1 MySQL Package Installer: DMG Contents

Double-click the MySQLStartItem.pkg file to start the installation process.

You will be presented with the Install MySQL Startup Item dialog.

Figure 4.2 MySQL Startup Item Installer: Introduction

Click Continue to continue the installation process.

A copy of the installation instructions and other important information relevant to this installation are displayed. Click Continue .

Select the drive you want to use to install the MySQL Startup Item. The drive must have a valid, bootable, OS X operating system installed. Click Continue.

Figure 4.3 MySQL Startup Item Installer: Choose Your Hard drive

You will be asked to confirm the details of the installation. To change the drive on which the startup item is installed, click either Go Back or Change Install Location.... To install the startup item, click Install.

Once the installation has been completed successfully, you will be shown an Install Succeeded message.

Figure 4.4 MySQL Startup Item Installer: Summary

The Startup Item for MySQL is installed into /Library/StartupItems/MySQLCOM. The Startup Item installation adds a variable MYSQLCOM=-YES- to the system configuration file /etc/hostconfig. If you want to disable the automatic startup of MySQL, change this variable to MYSQLCOM=-NO-.

Note

Deselecting Automatically Start MySQL Server on Startup from the MySQL Preference Pane sets the MYSQLCOM variable to -NO-.

After the installation, you can start and stop the MySQL server from the MySQL Preference Pane (preferred), or by running the following commands in a terminal window. You must have administrator privileges to perform these tasks, and you may be prompted for your password.

If you have installed the Startup Item, use this command to start the server:

shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start

If you have installed the Startup Item, use this command to stop the server:

shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM stop

Chapter 5 Installing and Using the MySQL Preference Pane

The MySQL Package installer disk image also includes a custom MySQL Preference Pane that enables you to start, stop, and control automated startup during boot of your MySQL installation.

To install the MySQL Preference Pane:

Download and open the MySQL package installer package, which is provided on a disk image (.dmg) that includes the main MySQL installation package, the MySQLStartupItem.pkg installation package, and the MySQL.prefPane. Double-click the disk image to open it.

Figure 5.1 MySQL Package Installer: DMG Contents

Double-click the MySQL.prefPane. The MySQL System Preferences will open.

If this is the first time you have installed the preference pane, you will be asked to confirm installation and whether you want to install the preference pane for all users, or only the current user. To install the preference pane for all users you will need administrator privileges. If necessary, you will be prompted for the username and password for a user with administrator privileges.

If you already have the MySQL Preference Pane installed, you will be asked to confirm whether you want to overwrite the existing MySQL Preference Pane.

Note

The MySQL Preference Pane only starts and stops MySQL installation installed from the MySQL package installation that have been installed in the default location.

Once the MySQL Preference Pane has been installed, you can control your MySQL server instance using the preference pane. To use the preference pane, open the System Preferences... from the Apple menu. Select the MySQL preference pane by clicking the MySQL logo within the Other section of the preference panes list.

Figure 5.2 MySQL Preference Pane: Location

The MySQL Preference Pane shows the current status of the MySQL server, showing stopped (in red) if the server is not running and running (in green) if the server has already been started. The preference pane also shows the current setting for whether the MySQL server has been set to start automatically.

To start the MySQL server using the preference pane:

Click Start MySQL Server. You may be prompted for the username and password of a user with administrator privileges to start the MySQL server.

To stop the MySQL server using the preference pane:

Click Stop MySQL Server. You may be prompted for the username and password of a user with administrator privileges to stop the MySQL server.

To automatically start the MySQL server when the system boots:

Check the check box next to Automatically Start MySQL Server on Startup.

To disable automatic MySQL server startup when the system boots:

Uncheck the check box next to Automatically Start MySQL Server on Startup.

You can close the System Preferences... window once you have completed your settings.

Chapter 6 Using the Bundled MySQL on OS X Server

If you are running OS X Server, a version of MySQL should already be installed. The following table shows the versions of MySQL that ship with OS X Server versions.

Table 6.1 MySQL Versions Preinstalled with OS X Server

OS X Server Version | MySQL Version
10.2-10.2.2 | 3.23.51
10.2.3-10.2.6 | 3.23.53
10.3 | 4.0.14
10.3.2 | 4.0.16
10.4.0 | 4.1.10a
10.5.0 | 5.0.45
10.6.0 | 5.0.82

The following table shows the installation layout of MySQL on OS X Server.

Table 6.2 MySQL Directory Layout for Preinstalled MySQL Installations on OS X Server

Directory | Contents of Directory
/usr/bin | Client programs
/var/mysql | Log files, databases
/usr/libexec | The mysqld server
/usr/share/man | Unix manual pages
/usr/share/mysql/mysql-test | MySQL test suite
/usr/share/mysql | Miscellaneous support files, including error messages, character set files, sample configuration files, SQL for database installation
/var/mysql/mysql.sock | Location of the MySQL Unix socket

Additional Resources

For more information on managing the bundled MySQL instance in OS X Server 10.5, see Mac OS X Server: Web Technologies Administration For Version 10.5 Leopard.

For more information on managing the bundled MySQL instance in OS X Server 10.6, see Mac OS X Server: Web Technologies Administration Version 10.6 Snow Leopard.

The MySQL server bundled with OS X Server does not include the MySQL client libraries and header files required to access and use MySQL from a third-party driver, such as Perl DBI or PHP. For more information on obtaining and installing MySQL libraries, see OS X Server version 10.5: MySQL libraries available for download. Alternatively, you can ignore the bundled MySQL server and install MySQL from the package or tarball installation.

Chapter 7 General Notes on Installing MySQL on OS X

You should keep the following issues and notes in mind:

OS X 10.4 deprecated startup items in favor of launchd daemons, and as of OS X 10.10 (Yosemite), startup items do not function. For these reasons, using launchd daemons is preferred over startup items.

The default location for the MySQL Unix socket is different on OS X and OS X Server depending on the installation type you chose. The following table shows the default locations by installation type.

Table 7.1 MySQL Unix Socket Locations on OS X by Installation Type

Installation Type | Socket Location
Package Installer from MySQL | /tmp/mysql.sock
Tarball from MySQL | /tmp/mysql.sock
MySQL Bundled with OS X Server | /var/mysql/mysql.sock

To prevent issues, you should either change the configuration of the socket used within your application (for example, changing php.ini), or you should configure the socket location using a MySQL configuration file and the socket option. For more information, see Server Command Options.

You may need (or want) to create a specific mysql user to own the MySQL directory and data. You can do this through the Directory Utility, and the mysql user should already exist. For use in single user mode, an entry for _mysql (note the underscore prefix) should already exist within the system /etc/passwd file.

If you get an “insecure startup item disabled” error when MySQL launches, use the following procedure. Adjust the pathnames appropriately for your system.

Modify the mysql.script using this command (enter it on a single line):

shell> sudo /Applications/TextEdit.app/Contents/MacOS/TextEdit
  /usr/local/mysql/support-files/mysql.server

Locate the option file that defines the basedir value and modify it to contain these lines:

basedir=/usr/local/mysql
datadir=/usr/local/mysql/data

In the /Library/StartupItems/MySQLCOM/ directory, make the following group ID changes from staff to wheel:

shell> sudo chgrp wheel MySQLCOM StartupParameters.plist

Start the server from System Preferences or Terminal.app.

Because the MySQL package installer installs the MySQL contents into a version and platform specific directory, you can use this to upgrade and migrate your database between versions. You will need to either copy the data directory from the old version to the new version, or alternatively specify an alternative datadir value to set location of the data directory.

You might want to add aliases to your shell's resource file to make it easier to access commonly used programs such as mysql and mysqladmin from the command line. The syntax for bash is:

alias mysql=/usr/local/mysql/bin/mysql
alias mysqladmin=/usr/local/mysql/bin/mysqladmin

For tcsh, use:

alias mysql /usr/local/mysql/bin/mysql
alias mysqladmin /usr/local/mysql/bin/mysqladmin

Even better, add /usr/local/mysql/bin to your PATH environment variable. You can do this by modifying the appropriate startup file for your shell. For more information, see Invoking MySQL Programs.

After you have copied over the MySQL database files from the previous installation and have successfully started the new server, you should consider removing the old installation files to save disk space. Additionally, you should also remove older versions of the Package Receipt directories located in /Library/Receipts/mysql-VERSION.pkg.