~ubuntu-branches/ubuntu/precise/libdbi-drivers/precise

<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<!-- $Id: dbd_mysql.sgml,v 1.3 2005/07/17 00:58:09 mhoenicka Exp $ -->

<book>

  <bookinfo>

    <title>mysql driver manual</title>

    <subtitle>A libdbi driver providing connectivity to MySQL databases using libmysqlclient.</subtitle>

  <author>

      <firstname>Mark</firstname>

      <surname>Tobenkin</surname>

      <affiliation>

        <address><email>mmt@users.sourceforge.net</email></address>

      </affiliation>

    </author>

    <revhistory>

      <revision>

        <revnumber>0.4</revnumber>

        <date>2005-07-15</date>

      </revision>

      <revision>

        <revnumber>0.3</revnumber>

        <date>2003-4-12</date>

      </revision>

      <revision>

        <revnumber>0.2</revnumber>

        <date>2003-2-4</date>

      </revision>

      <revision>

        <revnumber>0.1</revnumber>

        <date>2002-11-5</date>

      </revision>

    </revhistory>

  </bookinfo>

  <preface>

    <title>Preface</title>

    <para><ulink url="http://libdbi.sourceforge.net">libdbi</ulink> is a database abstraction layer written in C. It implements a framework that can utilize separate driver libraries for specific database servers. The <ulink url="http://libdbi-drivers.sourceforge.net">libdbi-drivers</ulink> project provides the drivers necessary to talk to the supported database servers.</para>

    <para>This manual provides information about the MySQL driver. The manual is intended for programmers who write applications linked against libdbi and who want their applications to work with the MySQL driver.</para>

    <para>Questions and comments about the MySQL driver should be sent to the <ulink url="mailto:libdbi-drivers-devel@lists.sourceforge.net">libdbi-drivers-devel</ulink> mailing list. Visit the <ulink url="http://lists.sourceforge.net/lists/listinfo/libdbi-drivers-devel">libdbi-drivers-devel list page</ulink> to subscribe and for further information. Questions and comments about the libdbi library should be sent to the appropriate libdbi mailing list.</para>

    <para>The MySQL driver is maintained by <ulink url="mailto:mmt@users.sourceforge.net">Mark Tobenkin</ulink>.</para>

  </preface>

  <chapter>

    <title>Introduction</title>

    <para><ulink url="http://www.mysql.org">MySQL</ulink>, as of the time of this document's writing, is one of the fastest growing database systems worldwide. With approximately 4 million installations, and 30,000 daily downloads, the server has found a niche in the website development community. Quick deployment and ease of use are among it's assets.</para>

  </chapter>

  <chapter>

    <title>Installation</title>

    <para>This chapter describes the prerequisites and the procedures to build and install the mysql driver from the sources.</para>

    <sect1>

      <title>Prerequisites</title>

      <para>The following packages have to be installed on your system:</para>

      <variablelist>

        <varlistentry>

          <term>libdbi</term>

          <listitem>

            <para>This library provides the framework of the database abstraction layer which can utilize the MySQL driver to perform database operations. The download page as well as the mailing lists with bug reports and patches are accessible at <ulink url="http://sourceforge.net/projects/libdbi">sourceforge.net/projects/libdbi</ulink>. The current version of the MySQL driver requires libdbi version 0.8.x.</para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>libmysqlclient</term>

          <listitem>

            <para>This library implements the client API for MySQL programs. Find the most recent release at <ulink url="http://www.mysql.org">www.mysql.org</ulink>. The current version of the mysql driver was tested with MySQL version 4.1.10a, and it should work with other 4.x releases.</para>

          </listitem>

        </varlistentry>

      </variablelist>

    </sect1>

    <sect1>

      <title>Build and install the mysql driver</title>

      <para>First you have to unpack the libdbi-drivers archive in a suitable directory. Unpacking will create a new subdirectory <filename class="directory">libdbi-drivers-X.Y</filename> where "X.Y" denotes the version:</para>

      <screen><prompt>$ </prompt><userinput>tar -xzf libdbi-drivers-X.Y.tar.gz</userinput></screen>

      <para>The libdbi-drivers project consists of several drivers that use a common build system. Therefore you <emphasis>must</emphasis> tell configure explicitly that you want to build the mysql driver (you can list as many drivers as you want to build):</para>

      <screen><prompt>$ </prompt><userinput>cd libdbi-drivers</userinput></screen>

      <screen><prompt>$ </prompt><userinput>./configure --with-mysql</userinput></screen>

      <para>Run <command>./configure --help</command> to find out about additional options.</para>

      <para>Then build the driver with the command:</para>

      <screen><prompt>$ </prompt><userinput>make</userinput></screen>

      <note>

        <para>Please note that you may have to invoke <command>gmake</command>, the GNU version of make, on some systems.</para>

      </note>

      <para>Then install the driver with the command (you'll need root permissions to do this):</para>

      <screen><prompt>$ </prompt><userinput>make install</userinput></screen>

      <para>To test the operation of the newly installed driver, use the command:</para>

      <screen><prompt>$ </prompt><userinput>make check</userinput></screen>

      <para>This command creates and runs a test program that performs a few basic input and output tests. The program will ask for an administrator username and password. This user can be any user who has database creation priveleges. Be sure to provide the name of a database which does not already exist (avoid 'test' which is used on many systems).</para>

      <note>

        <para>If for some reason you need to re-create the autoconf/automake-related files, try running <command moreinfo="none">./autogen.sh</command>. I've found out that the current stable autoconf/automake/libtool versions (as found in FreeBSD 4.7 and Debian 3.0) do not cooperate well, so I found it necessary to run the older autoconf 2.13. If necessary, edit <filename moreinfo="none">autogen.sh</filename> so that it will catch the older autoconf version on your system.</para>

      </note>

    </sect1>

  </chapter>

  <chapter>

    <title>Driver options</title>

    <para>Your application has to initialize libdbi drivers by setting some driver options with the <function>dbi_conn_set_option()</function> and the <function>dbi_conn_set_option_numeric()</function> library functions. The mysql driver supports the following options:</para>

    <variablelist>

      <varlistentry>

        <term>host</term>

        <listitem>

          <para>The hostname or IP address of the MySQL database server. Use an empty string or "localhost" to connect to a MySQL server running on the local machine.</para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>port (numeric)</term>

        <listitem>

          <para>The port used to remotely connect to the MySQL database server over TCP. Use "0" (zero) to accept the default socket.</para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>username</term>

        <listitem>

          <para>The name of the user accessing the database.</para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>password</term>

        <listitem>

          <para>The password of the user accessing the database.</para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>dbname</term>

        <listitem>

          <para>The name of the database used for the initial connection. If your program must be able to connect to a fresh MySQL installation, use the system database <filename moreinfo="none">mysql</filename>.</para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>encoding</term>

        <listitem>

          <para>The IANA name of a character encoding which is to be used as the connection encoding. Input and output data will be silently converted from and to this character encoding, respectively. The list of available character encodings depends on your local MySQL installation. If you set this option to "auto", the connection encoding will be the same as the default encoding of the database.</para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>mysql_include_trailing_null (numeric)</term>

        <listitem>

          <para>This item will tell the driver whether or not to include trailing null values ('\0') at the end of binary strings. This applies to the types BLOB, MEDIUMBLOB, LARGEBLOB etc. A numeric value of 0 will tell the driver to leave off the NULL value. A value of 1 will tell the driver to include the trailing NULL character. </para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>mysql_unix_socket</term>

        <listitem>

          <para>The filename of the Unix socket used to connect to a MySQL database server running on the local machine. Provide an empty string to use the default socket.</para>

        </listitem>

      </varlistentry>

      <varlistentry>

        <term>mysql_compression (numeric)</term>

        <listitem>

          <para>A value larger than zero causes the client/server communication to be compressed. Set this to zero to use no data compression.</para>

        </listitem>

      </varlistentry>

    </variablelist>

  </chapter>

  <chapter>

    <title>Peculiarities you should know about</title>

    <para>This chapter lists known peculiarities of the mysql driver. This includes MySQL features that differ from what you know from the other database servers supported by libdbi, and it includes features and misfeatures introduced by the mysql driver. It is the intention of the driver author to reduce the number of misfeatures in future releases if possible.</para>

    <sect1>

      <title>MySQL (mis)features</title>

      <itemizedlist>

        <listitem>

          <para>To allow for row seeking, results are loaded into memory. This is very inefficient and may provide a bottleneck for large applications.</para>

        </listitem>

        <listitem>

          <para>DATETIME, TIMESTAMP, DATE and TIME are all treated as the DBI type DATETIME. This is currently a string, but will change in later releases.</para>

        </listitem>

        <listitem>

          <para>The DECIMAL type is treated as a string, as it has arbitrary precision.</para>

        </listitem>

      </itemizedlist>

    </sect1>

  </chapter>

</book>