mysql-otp/doc/overview.edoc

MySQL/OTP – MySQL client library for Erlang/OTP
Copyright (C) 2014 Viktor Söderqvist

This file is part of MySQL/OTP.

MySQL/OTP is free software: you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
more details.

You should have received a copy of the GNU Lesser General Public License
along with this program. If not, see <https://www.gnu.org/licenses/>.
------------------------------------------------------------------------

@title MySQL/OTP client library
@doc
MySQL/OTP is a client library for connecting to MySQL databases from Erlang/OTP
applications. It is a native implementation of the MySQL protocol in Erlang.

This is the documentation generated from the Erlang source code using EDoc.
The source code is available on the github page <a target="_top"
 href="https://github.com/mysql-otp/mysql-otp/">
https://github.com/mysql-otp/mysql-otp/</a> along with a wiki and an issue
tracker. Coverage reports from the EUnit tests are available <a target="_top"
 href="../.eunit/index.html">here</a>.

This library is free software licensed under the GNU LGPL which allows you to
use it in proprietary applications as well as free software applications with
other licenses. This documentation is generated from the source code and thus
goes under the same license as the library itself. The license files are
available in the files <a href="../COPYING" target="_top">COPYING</a> and
<a href="../COPYING.LESSER" target="_top">COPYING.LESSER</a>.

<h2>API functions</h2>

The <a href="mysql.html">mysql</a> module contains all the API functions for
connecting to and interacting with a MySQL server.

<h2 id="value-representation">Value representation</h2>

<table>
  <thead>
    <tr>
      <th>MySQL</th>
      <th>Erlang</th>
      <th>Example</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>INT, TINYINT, etc.</td>
      <td>`integer()'</td>
      <td>`42'</td>
    </tr>
    <tr>
      <td>VARCHAR, TEXT, etc.</td>
      <td>`iodata()' [<a href="#vn1">1</a>]</td>
      <td>`<<"foo">>, "bar"'</td>
    </tr>
    <tr>
      <td>FLOAT, DOUBLE</td>
      <td>`float()'</td>
      <td>`3.14'</td>
    </tr>
    <tr>
      <td>DECIMAL</td>
      <td>`binary()' [<a href="#vn2">2</a>]</td>
      <td>`<<"3.140">>'</td>
    </tr>
    <tr>
      <td>DATETIME, TIMESTAMP</td>
      <td>`calendar:datetime()' [<a href="#vn3">3</a>]</td>
      <td>`{{2014, 11, 18}, {10, 22, 36}}'</td>
    </tr>
    <tr>
      <td>DATE</td>
      <td>`calendar:date()'</td>
      <td>`{2014, 11, 18}'</td>
    </tr>
    <tr>
      <td>TIME</td>
      <td>`{Days, calendar:time()}' [<a href="#vn3">3</a>,
          <a href="#vn4">4</a>]</td>
      <td>`{0, {10, 22, 36}}'</td>
    </tr>
    <tr>
      <td>NULL</td>
      <td>`null'</td>
      <td>`null'</td>
    </tr>
  </tbody>
</table>

Notes:

<ol>
  <li id="vn1">When fetching VARCHAR, TEXT etc. they are returned as `binary()'.
    When sending (insert or update) any `iodata()' is accepted.</li>
  <li id="vn2">DECIMAL are currently always returned as `binary()'. This will
    probably be changed to something similar to how the `odbc' OTP application
    handles them, namely
    <ul>
      <li>`integer()' when there are no fractions;</li>
      <li>`float()' when the precision of a float is exact enough;</li>
      <li>`binary()' when the precision of a float is not enough.</li>
    </ul>
  </li>
  <li id="vn3">For `DATETIME', `TIMESTAMP' and `TIME' values with franctions of
    seconds, we use a float for the seconds part. (These are unusual and were
    added to MySQL in version 5.6.4.)</li>
  <li id="vn4">Since `TIME' can be outside the `calendar:time()' interval, we use
    the format as returned by calendar:seconds_to_daystime/1 for `TIME'
    values.</li>
</ol>

<h2>Example with Poolboy</h2>

TODO