2.5 Installing MySQL on Mac OS X
================================

Beginning with MySQL 4.0.11, you can install MySQL on Mac OS X 10.2.x
("Jaguar") and up 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) 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.

To obtain MySQL, see *Note getting-mysql::.

*Note*: Before proceeding with the    installation, be sure to shut
down all running MySQL server instances    by either using the MySQL
Manager Application (on Mac OS X Server) or    via `mysqladmin
shutdown' on the command line.

To actually install the MySQL PKG file, double-click on the package
icon. This launches the Mac OS X Package Installer, which guides you
through the installation of MySQL.

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

The Mac OS X PKG of MySQL installs itself into
`/usr/local/mysql-VERSION'    and also installs a symbolic link,
`/usr/local/mysql', pointing to the new location.     If a directory
named `/usr/local/mysql' exists, it    is renamed to
`/usr/local/mysql.bak' first.     Additionally, the installer creates
the grant tables in the    `mysql' database by executing
`mysql_install_db' after the installation.

The installation layout is similar to that of a    `tar' file binary
distribution; all MySQL binaries    are located in the directory
`/usr/local/mysql/bin'. The MySQL socket file is    created as
`/tmp/mysql.sock' by default. See    *Note installation-layouts::.

MySQL installation requires a Mac OS X user account named    `mysql'. A
user account with this name should exist    by default on Mac OS X 10.2
and up.

If you are running Mac OS X Server, you have a version of MySQL
installed. The versions of MySQL that ship with Mac OS X Server
versions are shown in the following table:

*Mac OS X Server       *MySQL Version*
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

This manual section covers the installation of the official MySQL Mac
OS X PKG only. Make sure to read Apple's help information about
installing MySQL: Run the "Help View" application, select "Mac OS    X
Server" help, do a search for "MySQL," and read the item    entitled
"Installing MySQL."

For pre-installed versions of MySQL on Mac OS X Server, note
especially that you should start `mysqld' with    `safe_mysqld' instead
of    `mysqld_safe' if MySQL is older than version 4.0.

If you previously used Marc Liyanage's MySQL packages for Mac OS X
from    http://www.entropy.ch (http://www.entropy.ch), you    can
simply follow the update instructions for packages using the    binary
installation layout as given on his pages.

If you are upgrading from Marc's 3.23.xx versions or from the Mac OS
X Server version of MySQL to the official MySQL PKG, you also need to
convert the existing MySQL privilege tables to the current format,
because some new security privileges have been added. See    *Note
upgrading-grant-tables::.

If you would like to automatically start up MySQL during system
startup, you also need to install the MySQL Startup Item. Starting
with MySQL 4.0.15, it is part of the Mac OS X installation disk
images as a separate installation package. Simply double-click the
`MySQLStartupItem.pkg' icon and follow the    instructions to install
it.

Note that the Startup Item need be installed only once! There is no
need to install it each time you upgrade the MySQL package later.

The Startup Item is installed into    `/Library/StartupItems/MySQLCOM'.
(Before MySQL    4.1.2, the location was
`/Library/StartupItems/MySQL', but that collided    with the MySQL
Startup Item installed by Mac OS X Server.) Startup    Item
installation adds a variable `MYSQLCOM=-YES-'    to the system
configuration file    `/etc/hostconfig'. If you would like to disable
the automatic startup of MySQL, simply change this variable to
`MYSQLCOM=-NO-'.

On Mac OS X Server, the default MySQL installation uses the variable
`MYSQL' in the `/etc/hostconfig'    file. The MySQL AB Startup Item
installer disables this variable by    setting it to `MYSQL=-NO-'. This
avoids boot time    conflicts with the `MYSQLCOM' variable used by the
 MySQL AB Startup Item. However, it does not shut down a running MySQL
  server. You should do that yourself.

After the installation, you can start up MySQL by running the
following commands in a terminal window. You must have administrator
privileges to perform this task.

If you have installed the Startup Item:

     shell> sudo /Library/StartupItems/MySQLCOM/MySQLCOM start
     (Enter your password, if necessary)
     (Press Control-D or enter "exit" to exit the shell)

For versions of MySQL older than 4.1.3, substitute
`/Library/StartupItems/MySQLCOM/MySQLCOM' with
`/Library/StartupItems/MySQL/MySQL' above.

If you don't use the Startup Item, enter the following command
sequence:

     shell> cd /usr/local/mysql
     shell> sudo ./bin/mysqld_safe
     (Enter your password, if necessary)
     (Press Control-Z)
     shell> bg
     (Press Control-D or enter "exit" to exit the shell)

You should be able to connect to the MySQL server, for example, by
running `/usr/local/mysql/bin/mysql'.

*Note*: The accounts that are listed    in the MySQL grant tables
initially have no passwords. After starting    the server, you should
set up passwords for them using the    instructions in *Note
post-installation::.

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 `tcsh' is:

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

For `bash', 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. For example, add the    following line to your
`$HOME/.tcshrc' file if    your shell is `tcsh':

     setenv PATH ${PATH}:/usr/local/mysql/bin

If no `.tcshrc' file exists in your home    directory, create it with a
text editor.

If you are upgrading an existing installation, please note that
installing a new MySQL PKG does not remove the directory of an older
installation. Unfortunately, the Mac OS X Installer does not yet
offer the functionality required to properly upgrade previously
installed packages.

To use your existing databases with the new installation, you'll need
to copy the contents of the old data directory to the new data
directory. Make sure that neither the old server nor the new one is
running when you do this. 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'.

