source: server/databases/mysql.xml@ 4a395712

<?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.6/mysql-&mysql-version;.tar.gz">
  <!ENTITY mysql-download-ftp  " ">
  <!ENTITY mysql-md5sum        "9241be729964ab4594de11baa30aec48">
  <!ENTITY mysql-size          "34 MB">
  <!ENTITY mysql-buildsize     "1.0 GB">
  <!ENTITY mysql-time          "4.5 SBU">
]>

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

    &lfs73_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="libevent"/> and
      <xref linkend="openssl"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <ulink url="http://packages.debian.org/source/sid/libaio">libaio</ulink> and
      <ulink url="http://www.thrysoee.dk/editline/">libedit</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. By default, it 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 it is recommend to use the shared
      libraries whenever it is possible.
    </para>

    <para>
      There are numerous options available to
      <command>cmake</command>. Check the output of the `<command>cmake .
      -LH</command>` for additional customization options. See the <ulink
      url="http://dev.mysql.com/doc/refman/5.6/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/plugin          \
      -DINSTALL_SBINDIR=sbin                        \
      -DINSTALL_SCRIPTDIR=bin                       \
      -DINSTALL_SQLBENCHDIR=share/mysql/bench       \
      -DINSTALL_SUPPORTFILESDIR=share/mysql         \
      -DMYSQL_DATADIR=/srv/mysql                    \
      -DMYSQL_UNIX_ADDR=/run/mysqld/mysqld.sock     \
      -DSYSCONFDIR=/etc/mysql                       \
      -DWITH_PARTITION_STORAGE_ENGINE=OFF           \
      -DWITH_PERFSCHEMA_STORAGE_ENGINE=OFF          \
      -DWITH_EXTRA_CHARSETS=complex                 \
      -DWITH_LIBEVENT=system                        \
      -DWITH_SSL=system                             \
      .. &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make test</command>.
    </para>

    <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>-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_EXTRA_CHARSETS=complex</parameter>: This switch enables
      support for the complex character sets.
    </para>

    <para>
      <parameter>-DWITH_LIBEVENT=system</parameter>: This switch is used to
      tell the build system to use installed <application>libevent</application>.
      Remove it if you didn't install <application>libevent</application>.
    </para>

    <para>
      <parameter>-DWITH_SSL=system</parameter>: This switch is used to tell the
      build system to use installed <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>

      <note>
        <para>
          If you are upgrading from previous major version of
          <application>MySQL</application>, be sure to consult
          the <ulink
          url="https://dev.mysql.com/doc/refman/5.6/en/upgrading-from-previous-series.html">
          MySQL Reference Manual</ulink> for notes on
          upgrading the software.
        </para>
      </note>

      <para>
        Create basic <filename>/etc/mysql/my.cnf</filename>
        using the following command as the <systemitem
        class="username">root</systemitem> user:
      </para>

<screen role="root"><userinput>install -v -dm755 /etc/mysql &amp;&amp;
cat &gt; /etc/mysql/my.cnf &lt;&lt; "EOF"
<literal># Begin /etc/mysql/my.cnf

# The following options will be passed to all MySQL clients
[client]
#password       = your_password
port            = 3306
socket          = /run/mysqld/mysqld.sock

# The MySQL server
[mysqld]
port            = 3306
socket          = /run/mysqld/mysqld.sock
datadir         = /srv/mysql
skip-external-locking
key_buffer = 16M
max_allowed_packet = 1M
sort_buffer_size = 512K
net_buffer_length = 16K
myisam_sort_buffer_size = 8M

# Don't listen on a TCP/IP port at all.
skip-networking

# required unique id between 1 and 2^32 - 1
server-id       = 1

# Uncomment the following if you are using BDB tables
#bdb_cache_size = 4M
#bdb_max_lock = 10000

# Uncomment the following if you are using InnoDB tables
#innodb_data_home_dir = /srv/mysql
#innodb_data_file_path = ibdata1:10M:autoextend
#innodb_log_group_home_dir = /srv/mysql
# You can set .._buffer_pool_size up to 50 - 80 %
# of RAM but beware of setting memory usage too high
#innodb_buffer_pool_size = 16M
#innodb_additional_mem_pool_size = 2M
# Set .._log_file_size to 25 % of buffer pool size
#innodb_log_file_size = 5M
#innodb_log_buffer_size = 8M
#innodb_flush_log_at_trx_commit = 1
#innodb_lock_wait_timeout = 50

[mysqldump]
quick
max_allowed_packet = 16M

[mysql]
no-auto-rehash
# Remove the next comment character if you are not familiar with SQL
#safe-updates

[isamchk]
key_buffer = 20M
sort_buffer_size = 20M
read_buffer = 2M
write_buffer = 2M

[myisamchk]
key_buffer_size = 20M
sort_buffer_size = 20M
read_buffer = 2M
write_buffer = 2M

[mysqlhotcopy]
interactive-timeout

# End /etc/mysql/my.cnf</literal>
EOF</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/mysqld &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_config_editor,
          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} and
          libmysqlservices.a
        </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.6/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>