glfs/server/databases/mysql.xml

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

  <!ENTITY mysql-download-http "http://cdn.mysql.com/Downloads/MySQL-5.5/mysql-&mysql-version;.tar.gz">
  <!ENTITY mysql-download-ftp  " ">
  <!ENTITY mysql-md5sum        "e6b9f9cb82e990bd8f0474df7462904e">
  <!ENTITY mysql-size          "24 MB">
  <!ENTITY mysql-buildsize     "760 MB (additional 170 MB to run the test suite)">
  <!ENTITY mysql-time          "4.0 SBU (Test suite is an additional 45 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>

    &lfs72_checked;

    <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">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Optional patch (recommended if building for Amarok):
          <ulink url="&patch-root;/mysql-&mysql-version;-embedded_library_shared-1.patch"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Optional Documentation (see tip below):
          <ulink url="http://dev.mysql.com/doc/"/>
        </para>
       </listitem>
    </itemizedlist>
    
    <bridgehead renderas="sect3">MySQL Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="cmake"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="openssl"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <ulink url="http://packages.debian.org/source/sid/libaio">libaio</ulink>
    </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. Issue the following (as
      <systemitem class="username">root</systemitem>) to create the
      user and group:
    </para>

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

    <para>
      If the MySQL server is not needed, it is possible to build only the
      client libraries of MySQL. To do this you need to add
      <parameter>-DWITHOUT_SERVER=ON</parameter> to the <command>cmake</command>
      command below.
    </para>

    <para>
      MySQL contains an embedded server library which can be enabled with
      the cmake option <parameter>-DWITH_EMBEDDED_SERVER=ON</parameter>. By
      default this server is built as a statically linked library,
      <filename>libmysqld.a</filename>, but by applying the optional patch, a
      shared version of this library can be built. The library is needed
      by certain applications, such as <application>Amarok</application> and
      we recommend use of the shared libraries.
    </para>
    
    <para>
      There are numerous options available to
      <userinput>cmake</userinput>. Check the output of the `<userinput>cmake .
      -LH</userinput>` for additional customization options. See the <ulink
      url="http://dev.mysql.com/doc/refman/5.5/en/source-configuration-options.html">MySQL
      Documentation</ulink> for a full listing of all options.
    </para>
    
    <para>
      If you want to build shared version of the embedded server library, apply
      the following patch:
    </para>
    
<screen><userinput>patch -Np1 -i ../mysql-&mysql-version;-embedded_library_shared-1.patch</userinput></screen>
    
    <para>
      Install <application>MySQL</application> by running the
      following commands:
    </para>
    
<screen><userinput>sed -i "/ADD_SUBDIRECTORY(sql\/share)/d" CMakeLists.txt &amp;&amp;
sed -i "s/ADD_SUBDIRECTORY(libmysql)/&amp;\\nADD_SUBDIRECTORY(sql\/share)/" CMakeLists.txt &amp;&amp;
sed -i "s@data/test@\${INSTALL_MYSQLSHAREDIR}@g" sql/CMakeLists.txt &amp;&amp;
sed -i "s@data/mysql@\${INSTALL_MYSQLTESTDIR}@g" sql/CMakeLists.txt &amp;&amp;
mkdir build &amp;&amp;
cd build &amp;&amp;
cmake -DCMAKE_BUILD_TYPE=Release                    \
      -DCMAKE_INSTALL_PREFIX=/usr                   \
      -DINSTALL_DOCDIR=share/doc/mysql              \
      -DINSTALL_DOCREADMEDIR=share/doc/mysql        \
      -DINSTALL_INCLUDEDIR=include/mysql            \
      -DINSTALL_INFODIR=share/info                  \
      -DINSTALL_MANDIR=share/man                    \
      -DINSTALL_MYSQLDATADIR=/srv/mysql             \
      -DINSTALL_MYSQLSHAREDIR=share/mysql           \
      -DINSTALL_MYSQLTESTDIR=share/mysql/test       \
      -DINSTALL_PLUGINDIR=lib/mysql                 \
      -DINSTALL_SBINDIR=sbin                        \
      -DINSTALL_SCRIPTDIR=bin                       \
      -DINSTALL_SQLBENCHDIR=share/mysql/bench       \
      -DINSTALL_SUPPORTFILESDIR=share/mysql/support \
      -DMYSQL_DATADIR=/srv/mysql                    \
      -DMYSQL_UNIX_ADDR=/var/run/mysql/mysql.sock   \
      -DSYSCONFDIR=/etc/mysql                       \
      -DWITH_PARTITION_STORAGE_ENGINE=OFF           \
      -DWITH_PERFSCHEMA_STORAGE_ENGINE=OFF          \
      -DWITH_READLINE=system                        \
      -DWITH_SSL=system                             \
      .. &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make test-force 2>&amp;1 | tee
      test.log</command>. This forces the test to run to completion and logs all
      the test output. There will be many tests that are not run due to
      configuration options and developer considerations. Otherwise many of the
      tests will fail. Also, two tests will fail if ipv6 is not available in
      the kernel either as a module or built in.
    </para>

    <note>
      <para>
        The SSL tests may fail due to expired certificates.
      </para>
    </note>
    
    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

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

    <tip>
      <para>
        The only documentation shipped in the source tarball are
        <filename>mysql.info</filename> and man pages. You can download
        various formats of the <application>MySQL</application>
        Reference Manual from <ulink url="http://dev.mysql.com/doc/"/>.
      </para>
    </tip>

  </sect2>

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

    <para>
      <command>sed -i ...</command>: First two seds fix client-only builds. Last
      two seds set correct installation directories for some components.
    </para>

    <para>
      <parameter>-DWITH_&lt;engine&gt;_STORAGE_ENGINE=ON</parameter>: The default
      instructions only build the innobase (InnoDB) storage engine. If other
      storage engines are desired use this switch to enable them. Valid choices
      are ARCHIVE, BLACKHOLE, EXAMPLE, FEDERATED, INNOBASE, NDBCLUSTER,
      PARTITION and PERFSCHEMA.
    </para>

    <para>
      <parameter>-DWITHOUT_SERVER=ON</parameter>: Use this switch if you don't
      want the server and would like to build the client only.
    </para>

    <para>
      <parameter>-DWITH_EMBEDDED_SERVER=ON</parameter>: Use this switch to build
      the embedded server library.
    </para>
    
    <para>
      <parameter>-DWITH_SSL=system</parameter>: This switch is used to tell the
      build system to use system version of the
      <application>OpenSSL</application>. Remove it if you didn't install
      <application>OpenSSL</application>.
    </para>

  </sect2>

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

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

      <para>
        <filename>/etc/mysql/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-mysql-my.cnf">/etc/mysql/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. When creating the file, ensure binary logs are disabled unless you
        are doing database replication. Create <filename>/etc/mysql/my.cnf</filename>
        using the following commands as the <systemitem
        class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>install -v -Dm644 /usr/share/mysql/support/my-medium.cnf /etc/mysql/my.cnf &amp;&amp;
sed -i 's/^log-bin/#log-bin/' /etc/mysql/my.cnf &amp;&amp;
sed -i 's/^binlog/#binlog/' /etc/mysql/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 --basedir=/usr --datadir=/srv/mysql --user=mysql &amp;&amp;
chown -R mysql:mysql /srv/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>
          innochecksum, msql2mysql, myisamchk, myisam_ftdump, myisamlog,
          myisampack, my_print_defaults, mysql, mysqlaccess, mysqlaccess.conf,
          mysqladmin, mysqlbinlog, mysqlbug, mysqlcheck, mysql_client_test,
          mysql_client_test_embedded, mysql_config, mysql_convert_table_format,
          mysqld, mysqld_multi, mysqld_safe, mysqldump, mysqldumpslow,
          mysql_embedded, mysql_find_rows, mysql_fix_extensions, mysqlhotcopy,
          mysqlimport, mysql_install_db, mysql_plugin, mysql_secure_installation,
          mysql_setpermission, mysqlshow, mysqlslap, mysqltest,
          mysqltest_embedded, mysql_tzinfo_to_sql, mysql_upgrade, mysql_waitpid,
          mysql_zap, perror, replace, resolveip and resolve_stack_dump
        </seg>
        <seg>
          libmysqlclient.{so,a}, libmysqlclient_r.{so,a}, libmysqld.{so,a},
          libmysqlservices.a and several in /usr/lib/mysql
        </seg>
        <seg>
          /etc/mysql,
          /srv/mysql,
          /usr/include/mysql,
          /usr/lib/mysql,
          /usr/share/doc/mysql and
          /usr/share/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.5/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>