source: server/databases/mysql.xml@ 9dcda46

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
   "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!-- <!ENTITY mysql-download-http "http://dev.mysql.com/get/Downloads/MySQL-5.0/mysql-&mysql-version;.tar.gz/from/http://mysql.mirrors.hoobly.com/"> -->
  <!-- <!ENTITY mysql-download-ftp  "ftp://mirror.mcs.anl.gov/pub/mysql/Downloads/MySQL-5.0/mysql-&mysql-version;.tar.gz"> -->
  <!ENTITY mysql-download-http "http://downloads.mysql.com/archives/mysql-5.0/mysql-&mysql-version;.tar.gz">
  <!ENTITY mysql-download-ftp  "ftp://ftp.freebsd.org/pub/FreeBSD/ports/distfiles/mysql-&mysql-version;.tar.gz">
  <!ENTITY mysql-md5sum        "c3165204c42e1db6fc3a95a4fd2cd22f">
  <!ENTITY mysql-size          "18.6 MB">
  <!ENTITY mysql-buildsize     "244 MB (additional 194 MB to run the test suite)">
  <!ENTITY mysql-time          "4.5 SBU (Test suite is an additional 48 minutes, only partially CPU dependent)">
]>

<sect1 id="mysql" xreflabel="MySQL-&mysql-version;">
  <?dbhtml filename="mysql.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>MySQL-&mysql-version;</title>

  <indexterm zone="mysql">
    <primary sortas="a-MySQL">MySQL</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to MySQL</title>

    <para><application>MySQL</application> is a widely used and fast SQL
    database server. It is a client/server implementation that consists of a
    server daemon and many different client programs and libraries.</para>

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&mysql-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&mysql-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &mysql-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &mysql-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &mysql-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &mysql-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">MySQL Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional"><xref linkend="openssl"/> and
    <xref linkend="tcpwrappers"/>.

    <!-- Removing libedit because it causes more problems than it solves.

    <ulink url="http://sourceforge.net/projects/libedit/">libedit</ulink>
    (as an alternative to readline)-->

    </para>

    <!-- These appear to be obsolete now that the docs have been pulled
         out of the main tarball. Configure still checks for them, but
         best I can tell, they are not used, nor can be used even if found

    <xref linkend="doxygen"/> and
    <xref linkend="tetex"/></para>
    -->

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/mysql"/></para>

  </sect2>

  <sect2 role="installation">
    <title>Installation of MySQL</title>

    <para>For security reasons, running the server as an unprivileged user
    and group is strongly encouraged:</para>

<screen role="root"><userinput>groupadd -g 40 mysql &amp;&amp;
useradd -c "MySQL Server" -d /dev/null -g mysql -s /bin/false \
        -u 40 mysql</userinput></screen>

    <para>Build and install <application>MySQL</application> by
    running the following commands:</para>

    <!-- Removing the CPPFLAGS="-D_GNU_SOURCE" and
         -with-named-thread-libs=-lpthread as they don't appear to be
         required any longer
    -->

<screen><userinput>C_EXTRA_FLAGS=-fno-strict-aliasing \
./configure --prefix=/usr \
            --sysconfdir=/etc \
            --libexecdir=/usr/sbin \
            --localstatedir=/srv/mysql \
            --enable-thread-safe-client \
            --enable-assembler \
            --enable-local-infile \
            --with-unix-socket-path=/var/run/mysql/mysql.sock \
            --without-debug \
            --without-bench \
            --without-readline \
            --with-berkeley-db \
            --with-extra-charsets=all &amp;&amp;
make testdir=/tmp/mysql</userinput></screen>

<!--
    <para>Some of the tests in the test suite are known to fail and this will
    cause the test suite to abort at that point. Issue the following command
    to disable the tests known to fail:</para>

<screen><userinput>for TESTFILE in information_schema innodb join mysql_client_test \
                ps_2myisam ps_3innodb ps_4heap ps_5merge \
                sp-error strict type_float type_ranges
do
  mv mysql-test/t/$TESTFILE.test mysql-test/t/$TESTFILE.test.disabled
done
unset TESTFILE</userinput></screen>
-->

    <para>To test the results, issue: <command>make test</command>. Note that
    if you have a restrictive <filename>/etc/hosts.deny</filename> file, you
    will need to add an appropriate entry to the
    <filename>/etc/hosts.allow</filename> file for the
    <command>mysqld</command> daemon, else many of the tests will fail.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make testdir=/tmp/mysql install &amp;&amp;
rm -rf /tmp/mysql &amp;&amp;
cd /usr/lib &amp;&amp;
ln -v -sf mysql/libmysqlclient{,_r}.so* .</userinput></screen>

<!-- Insert this back into the 'root' installation section if
     there are ever docs to install again

install -v -d -m755 /usr/share/mysql/Docs/Images &amp;&amp;
install -v -m644 Docs/manual{,_toc}.html \
                 Docs/manual.txt /usr/share/mysql/Docs &amp;&amp;
install -v -m644 Docs/Images/*.{jpg,gif} /usr/share/mysql/Docs/Images &amp;&amp;

-->

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para><parameter>C_EXTRA_FLAGS=-fno-strict-aliasing</parameter>: This
    environment variable adjusts the compiler optimization to avoid failures in
    the testsuite and other operations.</para>

    <para><parameter>--libexecdir=/usr/sbin</parameter>: This switch installs
    the <command>mysqld</command> daemon and the
    <command>mysqlmanager</command> program in an appropriate location.</para>

    <para><parameter>--localstatedir=/srv/mysql</parameter>: This switch
    forces <application>MySQL</application> to use
    <filename class='directory'>/srv/mysql</filename> for database files and
    other variable data.</para>

    <para><parameter>--enable-thread-safe-client</parameter>: This
    switch compiles a thread-safe <application>MySQL</application> client
    library.</para>

    <para><parameter>--enable-assembler</parameter>: This switch allows using
    assembler versions of some string functions.</para>

    <para><parameter>--enable-local-infile</parameter>: This switch enables
    the <quote>LOAD DATA INFILE</quote> SQL statement.</para>

    <para><parameter>--with-unix-socket-path=/var/run/mysql</parameter>:
    This switch puts the unix-domain socket into the
    <filename class="directory">/var/run/mysql</filename> directory instead of
    the default <filename class="directory">/tmp</filename>.</para>

    <para><parameter>--without-bench</parameter>: This switch skips building
    the benchmark suite.</para>

    <para><parameter>--without-readline</parameter>: This switch forces the
    build to use the system copy of <application>readline</application> instead
    of the bundled copy.</para>

    <para><parameter>--with-berkeley-db</parameter>: This switch enables
    using <application>Berkeley DB</application> tables as a back end.</para>

    <para><parameter>--with-extra-charsets=all</parameter>: This switch enables
    international character sets within the suite.</para>

    <para><command>make testdir=...</command>: This installs the test suite in
    <filename class='directory'>/tmp/mysql</filename>. The test suite is not
    required, nor does it function properly on an installed version of
    <application>MySQL</application>, so it is removed in the next step.</para>

    <para><command>ln -v -sf mysql/libmysqlclient{,_r}.so* .</command>: This
    command makes the <application>MySQL</application> shared libraries
    available to other packages at run-time.</para>

    <para><option>--with-openssl</option>: This switch adds OpenSSL support
    to <application>MySQL</application>.</para>

    <para><option>--with-libwrap</option>: This switch adds tcpwrappers
    support to <application>MySQL</application>.</para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring MySQL</title>

    <sect3 id="mysql-config">
      <title>Config Files</title>

      <para><filename>/etc/my.cnf</filename> and
      <filename>~/.my.cnf</filename></para>

      <indexterm zone="mysql mysql-config">
        <primary sortas="e-AA.my.cnf">~/.my.cnf</primary>
      </indexterm>

      <indexterm zone="mysql mysql-config">
        <primary sortas="e-etc-my.cnf">/etc/my.cnf</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>There are several default configuration files available in
      <filename class="directory">/usr/share/mysql</filename> which you can
      use. Create <filename>/etc/my.cnf</filename> using the following command
      as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m644 /usr/share/mysql/my-medium.cnf /etc/my.cnf</userinput></screen>

      <para>You can now install a database and change the ownership to the
      unprivileged user and group (perform as the <systemitem
      class="username">root</systemitem> user):</para>

<screen role="root"><userinput>mysql_install_db --user=mysql &amp;&amp;
chgrp -v mysql /srv/mysql{,/test,/mysql}</userinput></screen>

      <para>Further configuration requires that the
      <application>MySQL</application> server is running. Start
      the server using the following commands as the <systemitem
      class="username">root</systemitem> user:</para>

<screen role="root"><userinput>install -v -m755 -o mysql -g mysql -d /var/run/mysql &amp;&amp;
mysqld_safe --user=mysql 2&gt;&amp;1 &gt;/dev/null &amp;</userinput></screen>

      <para>A default installation does not set up a password for the
      administrator, so use the following command as the <systemitem
      class="username">root</systemitem> user to set one. Replace
      <replaceable>&lt;new-password&gt;</replaceable> with your own.</para>

<screen role="root"><userinput>mysqladmin -u root password <replaceable>&lt;new-password&gt;</replaceable></userinput></screen>

      <para>Configuration of the server is now finished. Shut the server
      down using the following command as the <systemitem
      class="username">root</systemitem> user:</para>

<screen role="root"><userinput>mysqladmin -p shutdown</userinput></screen>

    </sect3>

    <sect3  id="mysql-init">
      <title>Boot Script</title>

      <para>Install the <filename>/etc/rc.d/init.d/mysql</filename> init script
      included in the <xref linkend="bootscripts"/> package as
      the <systemitem class="username">root</systemitem> user to start the
      <application>MySQL</application> server during system boot-up.</para>

      <indexterm zone="mysql mysql-init">
        <primary sortas="f-mysql">mysql</primary>
      </indexterm>

<screen role="root"><userinput>make install-mysql</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>comp_err, innochecksum, msql2mysql, my_print_defaults,
        myisam_ftdump, myisamchk, myisamlog, myisampack, mysql,
        mysql_client_test, mysql_config, mysql_convert_table_format,
        mysql_create_system_tables, mysql_explain_log, mysql_find_rows,
        mysql_fix_extensions, mysql_fix_privilege_tables, mysql_install_db,
        mysql_secure_installation, mysql_setpermission, mysql_tableinfo,
        mysql_tzinfo_to_sql, mysql_waitpid, mysql_zap, mysqlaccess, mysqladmin,
        mysqlbinlog, mysqlbug, mysqlcheck, mysqld, mysqld_multi, mysqld_safe,
        mysqldump, mysqldumpslow, mysqlhotcopy, mysqlimport, mysqlmanager,
        mysqlshow, mysqltest, mysqltestmanager, mysqltestmanager-pwgen,
        mysqltestmanagerc, perror, replace, resolve_stack_dump, and
        resolveip</seg>
        <seg>libdbug.a, libheap.a, libmyisam.a, libmyisammrg.a,
        libmysqlclient.{so,a}, libmysqlclient_r.{so,a}, libmystrings.a,
        libmysys.a, and libvio.a</seg>
        <seg>/srv/mysql, /usr/include/mysql, /usr/lib/mysql, /usr/share/mysql, and
        /var/run/mysql</seg>
      </seglistitem>
    </segmentedlist>

    <bridgehead renderas="sect3">Short Descriptions</bridgehead>

    <para>Descriptions of all the programs and libraries would be several
    pages long. Instead, consult the <filename>mysql.info</filename>
    documentation or the on-line reference manual at <ulink
    url="http://dev.mysql.com/doc/refman/5.0/en/index.html"/>.</para>

    <para>The <application>Perl</application> DBI modules must be installed
    for some of the <application>MySQL</application> support programs to
    function properly.</para>

  </sect2>

</sect1>