2.4. Installing MySQL on Mac OS X

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

     * Native Package Installer format, which uses the native
       Mac OS X installer to walk you through the installation
       of MySQL. For more information, see Section 2.4.2,
       "Installing MySQL on Mac OS X Using Native Packages." You
       can use the package installer with Mac OS X 10.3 and
       later, and the package is available for both PowerPC and
       Intel architectures, and 32-bit and 64-bit architectures.
       There is no Universal Binary available using the package
       installation method. 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, Section 2.2,
       "Installing MySQL from Generic Binaries on
       Unix/Linux."You can use the package installer with Mac OS
       X 10.3 and later, and available for both PowerPC and
       Intel architectures, and both 32-bit and 64-bit
       architectures. A Universal Binary, incorporating both
       Power PC and Intel architectures and 32-bit and 64-bit
       binaries is available.
       In addition to the core installation, the Package
       Installer also includes Section 2.4.3, "Installing the
       MySQL Startup Item" and Section 2.4.4, "Installing and
       Using the MySQL Preference Pane," both of which simplify
       the management of your installation.

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

   For additional information on using MySQL on Mac OS X, see
   Section 2.4.1, "General Notes on Installing MySQL on Mac OS
   X."

2.4.1. General Notes on Installing MySQL on Mac OS X

   You should keep the following issues and notes in mind:

     * The default location for the MySQL Unix socket is
       different on Mac OS X and Mac OS X Server depending on
       the installation type you chose. The following table
       shows the default locations by installation type.
       Table 2.7. MySQL Unix Socket Locations on Mac 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 Mac 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 Section
       5.1.2, "Server Command Options."

     * You may need (or want) to create a specific mysql user to
       own the MySQL directory and data. On Mac OS X 10.4 and
       lower you can do this by using the Netinfo Manager
       application, located within the Utilities folder within
       the Applications folder. On Mac OS X 10.5 and later you
       can do this through the Directory Utility. From Mac OS X
       10.5 and later (including Mac OS X Server 10.5) the mysql
       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.

     * Due to a bug in the Mac OS X package installer, you may
       see this error message in the destination disk selection
       dialog:
You cannot install this software on this disk. (null)

       If this error occurs, click the Go Back button once to
       return to the previous screen. Then click Continue to
       advance to the destination disk selection again, and you
       should be able to choose the destination disk correctly.
       We have reported this bug to Apple and it is
       investigating this problem.

     * 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 Section 4.2.1, "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.

2.4.2. Installing MySQL on Mac OS X Using Native Packages

   You can install MySQL on Mac OS X 10.3.x ("Panther") or newer
   using a Mac OS X binary package in PKG format instead of the
   binary tarball distribution. Please note that older versions
   of Mac OS X (for example, 10.1.x or 10.2.x) are not supported
   by this package.

   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 Mac 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 Section 2.4.4,
   "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.39-osx10.5-x86_64.pkg installs
   MySQL into /usr/local/mysql-5.1.39-osx10.5-x86_64 . The
   following table shows the layout of the installation
   directory.

   Table 2.8. MySQL Installation Layout on Mac OS X
   Directory Contents of Directory
   bin Client programs and the mysqld server
   data Log files, databases
   docs Manual in Info format
   include Include (header) files
   lib Libraries
   man Unix manual pages
   mysql-test MySQL test suite
   scripts mysql_install_db
   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.

    1. 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.

    2. 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
       5.1.39, double-click mysql-5.1.39-osx10.5-x86.pkg.

    3. You will be presented with the opening installer dialog.
       Click Continue to begin installation.
       MySQL Package Installer: Step 1

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

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

    6. Select the drive you want to use to install the MySQL
       Startup Item. The drive must have a valid, bootable, Mac
       OS X operating system installed. Click Continue.
       MySQL Package Installer: Step 4

    7. 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 startup
       item is installed, click either Go Back or Change Install
       Location.... To install the startup item, click Install.

    8. 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 Section 2.4.3, "Installing the
   MySQL Startup Item," and Section 2.4.4, "Installing and Using
   the MySQL Preference Pane."

2.4.3. Installing the MySQL Startup Item

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

   To install the MySQL Startup Item:

    1. 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.

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

    3. You will be presented with the Install MySQL Startup Item
       dialog.
       MySQL Startup Item Installer: Step 1
       Click Continue to continue the installation process.

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

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

    6. 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.

    7. Once the installation has been completed successfully,
       you will be shown an Install Succeeded message.
       MySQL Startup Item Installer: Step 5

   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-.

   After the installation, you can start and stop MySQL 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

2.4.4. 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:

    1. 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.

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

    3. 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.

    4. 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.
   MySQL Preference Pane

   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 MySQL 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 MySQL 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 checkbox next to Automatically Start MySQL
       Server on Startup.

     * To disable automatic MySQL server startup when the system
       boots:
       Uncheck the checkbox next to Automatically Start MySQL
       Server on Startup.

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

2.4.5. Using the Bundled MySQL on Mac OS X Server

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

   Table 2.9. MySQL Versions Preinstalled with Mac OS X Server
   Mac 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
   Mac OS X Server.

   Table 2.10. MySQL Directory Layout for Preinstalled MySQL
   Installations on Mac 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 Mac OS X Server 10.5, see Mac OS X Server:
       Web Technologies Administration For Version 10.5 Leopard
       (http://images.apple.com/server/macosx/docs/Web_Technolog
       ies_Admin_v10.5.pdf).

     * For more information on managing the bundled MySQL
       instance in Mac OS X Server 10.6, see Mac OS X Server:
       Web Technologies Administration Version 10.6 Snow Leopard
       (http://manuals.info.apple.com/en_US/WebTech_v10.6.pdf).

     * The MySQL server bundled with Mac 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 Mac OS X
       Server version 10.5: MySQL libraries available for
       download (http://support.apple.com/kb/TA25017).
       Alternatively, you can ignore the bundled MySQL server
       and install MySQL from the package or tarball
       installation.
