Documentation

README.md

@@ -2,25 +2,27 @@ MySQL/OTP
 =========
 
 [![Build Status](https://travis-ci.org/mysql-otp/mysql-otp.svg)](https://travis-ci.org/mysql-otp/mysql-otp)
-[![LGPL](https://www.gnu.org/graphics/lgplv3-88x31.png)](#license)
 
-This is a MySQL driver for Erlang following the OTP principles.
+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.
 
-Status: Work in progress. Connecting and executing queries using the text protocol (plain queries) and binary protocols (prepared statements) work. The API and the value representation are subjects to change.
+Features:
 
-Background: We are starting this project with the aim at overcoming the problems with Emysql (the currently most popular driver) and erlang-mysql-driver (the even older driver).
-
-Design choices:
-
-* A connection is a gen_server.
-* No connection pool. Poolboy or your own supervisor can be used for this.
+* Works with MySQL 4.1 and later.
+* Mnesia style transactions.
+* Uses the binary protocol for prepared statements.
+* Each connection is a gen_server, which makes it compatible with Poolboy (for
+  connection pooling) and ordinary OTP supervisors.
 * No records in the public API.
-* API inspired by that of epgsql (the PostgreSQL driver).
 
-Contributing
-------------
+See also:
+
+* [API documenation](//mysql-otp.github.io/mysql-otp/doc/index.html) (Edoc)
+* [Test coverage](//mysql-otp.github.io/mysql-otp/.eunit/index.html) (EUnit)
+* [Why another MySQL driver?](https://github.com/mysql-otp/mysql-otp/wiki#why-another-mysql-driver) in the wiki
 
-We welcome contributors and new members of the project. We are open for suggestions about the API, the internal design and almost anything else. Let's use the project's wiki for discussions and TODOs.
+This is a work in progress. The API and the value representation may still
+change. Use a tagged version to make sure nothing breaks.
 
 Synopsis
 --------
@@ -29,20 +31,20 @@ Synopsis
 Opts = [{host, "localhost"}, {user, "foo"}, {password, "hello"},
         {database, "test"}],
 
-%% Connect and link to the connection process.
+%% Connect
 {ok, Pid} = mysql:start_link(Opts),
 
-%% A query returning results
+%% Select
 {ok, ColumnNames, Rows} = mysql:query(Pid, <<"SELECT * FROM mytable">>),
 
-%% A query not returning any rows just returns ok.
+%% Manipulate data
 ok = mysql:query(Pid, "INSERT INTO mytable (foo, bar) VALUES (1, 42)"),
 
-%% Named prepared statements.
+%% Named prepared statements
 {ok, foo} = mysql:prepare(Pid, "SELECT * FROM mytable WHERE id=?", foo),
 {ok, Columns, Rows} = mysql:execute(Pid, foo, [42]),
 
-%% Unnamed prepared statements.
+%% Unnamed prepared statements
 {ok, StmtId} = mysql:prepare(Pid, "SELECT * FROM mytable WHERE id=?"),
 {ok, Columns, Rows} = mysql:execute(Pid, StmtId, [42]).
 
@@ -75,27 +77,6 @@ case Result of
 end
 ```
 
-Value representation
---------------------
-
- MySQL              | Erlang                  | Examples
---------------------|-------------------------|-------------------
-INT, TINYINT, etc.  | integer()               | 42
-VARCHAR, TEXT, etc. | iodata()                | <<"foo">>, "bar"
-FLOAT, DOUBLE       | float()                 | 3.14
-DECIMAL             | binary()                | <<"3.140">>
-DATETIME, TIMESTAMP | calendar:datetime()     | {{2014, 11, 18}, {10, 22, 36}}
-DATE                | calendar:date()         | {2014, 11, 18}
-TIME                | {Days, calendar:time()} | {0, {10, 22, 36}}
-NULL                | null                    | null
-
-Since `TIME` can be outside the calendar:time() interval, we use the format as
-returned by `calendar:seconds_to_daystime/1` for `TIME` values.
-
-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.)
-
 Tests
 -----
 
@@ -106,20 +87,11 @@ MySQL running on localhost and give privileges to the `otptest` user:
 grant all privileges on otptest.* to otptest@localhost identified by 'otptest';
 ```
 
-Problems with Emysql
---------------------
-
-From the Emysql README:
+Contributing
+------------
 
-> The driver has several technical shortcomings:
->
-> * No clear protocol / connection pool separation
-> * No clear protocol / socket separation
-> * A very complicated connection pool management
-> * Uses the textual protocol in a lot of places where it shouldthe binary protocol
-> * The API could be better
->
->However, this is probably the best MySQL driver out there for Erlang. The erlang-mysql-driver uses a problematic connection pool design for many use cases and is not suitable for general purpose use. This driver is.
+Pull request and feature requests are welcome. If you're looking for something
+to do, pick one of the issues and solve it. Remember to include test cases.
 
 License
 -------

doc/overview.edoc

@@ -19,30 +19,29 @@ along with this program. If not, see <https://www.gnu.org/licenses/>.
 
 @title MySQL/OTP client library
 @doc
-This is the documentation generated from the Erlang source code using EDoc.
+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.
+tracker. Coverage reports from the EUnit tests are available <a target="_top"
+ href="../.eunit/index.html">here</a>.
 
-<img src="https://www.gnu.org/graphics/lgplv3-88x31.png" width="88" height="31"
-     style="float:right"/>
 This library is free software licensed under the GNU LGPL which allows you to
-use it in non-free applications and applications with other licenses. This
-documentation is generated from the source code and thus goes under the same
-license as the library itself.
+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.
-The <a href="mysql_connection.html">mysql_connection</a> module is the
-`gen_server' callback module holding a connection so you may want to refer to
-that sometimes (e.g. in the Modules part in a childspec for a supervisor). The
-other modules are for the internals.
+The <a href="mysql.html">mysql</a> module contains all the API functions for
+connecting to and interacting with a MySQL server.
 
-<h2>Value representation</h2>
+<h2 id="value-representation">Value representation</h2>
 
 <table>
   <thead>
@@ -60,7 +59,7 @@ other modules are for the internals.
     </tr>
     <tr>
       <td>VARCHAR, TEXT, etc.</td>
-      <td>`iodata()'</td>
+      <td>`iodata()' [<a href="#vn1">1</a>]</td>
       <td>`<<"foo">>, "bar"'</td>
     </tr>
     <tr>
@@ -70,12 +69,12 @@ other modules are for the internals.
     </tr>
     <tr>
       <td>DECIMAL</td>
-      <td>`binary()'</td>
+      <td>`binary()' [<a href="#vn2">2</a>]</td>
       <td>`<<"3.140">>'</td>
     </tr>
     <tr>
       <td>DATETIME, TIMESTAMP</td>
-      <td>`calendar:datetime()'</td>
+      <td>`calendar:datetime()' [<a href="#vn3">3</a>]</td>
       <td>`{{2014, 11, 18}, {10, 22, 36}}'</td>
     </tr>
     <tr>
@@ -85,7 +84,8 @@ other modules are for the internals.
     </tr>
     <tr>
       <td>TIME</td>
-      <td>`{Days, calendar: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>
@@ -96,6 +96,28 @@ other modules are for the internals.
   </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