Current section
Files
Jump to
Current section
Files
doc/mysql.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Module mysql</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
</head>
<body bgcolor="white">
<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<hr>
<h1>Module mysql</h1>
<ul class="index"><li><a href="#description">Description</a></li><li><a href="#types">Data Types</a></li><li><a href="#index">Function Index</a></li><li><a href="#functions">Function Details</a></li></ul>MySQL client.
<h2><a name="description">Description</a></h2><p>MySQL client.</p>
The <code>connection()</code> type is a gen_server reference as described in the
documentation for <code>gen_server:call/2,3</code>, e.g. the pid or the name if the
gen_server is locally registered.
<h2><a name="types">Data Types</a></h2>
<h3 class="typedecl"><a name="type-column_names">column_names()</a></h3>
<p><tt>column_names() = [binary()]</tt></p>
<h3 class="typedecl"><a name="type-connection">connection()</a></h3>
<p><tt>connection() = atom() | {Name::atom(), Node::atom()} | {global, GlobalName::term()} | {via, Module::atom(), ViaName::term()} | pid()</tt></p>
<h3 class="typedecl"><a name="type-query_filtermap_fun">query_filtermap_fun()</a></h3>
<p><tt>query_filtermap_fun() = fun((<a href="#type-row">row()</a>) -> <a href="#type-query_filtermap_res">query_filtermap_res()</a>) | fun((<a href="#type-column_names">column_names()</a>, <a href="#type-row">row()</a>) -> <a href="#type-query_filtermap_res">query_filtermap_res()</a>)</tt></p>
<h3 class="typedecl"><a name="type-query_filtermap_res">query_filtermap_res()</a></h3>
<p><tt>query_filtermap_res() = boolean() | {true, term()}</tt></p>
<h3 class="typedecl"><a name="type-query_result">query_result()</a></h3>
<p><tt>query_result() = ok | {ok, <a href="#type-column_names">column_names()</a>, <a href="#type-rows">rows()</a>} | {ok, [{<a href="#type-column_names">column_names()</a>, <a href="#type-rows">rows()</a>}, ...]} | {error, <a href="#type-server_reason">server_reason()</a>}</tt></p>
<h3 class="typedecl"><a name="type-row">row()</a></h3>
<p><tt>row() = [term()]</tt></p>
<h3 class="typedecl"><a name="type-rows">rows()</a></h3>
<p><tt>rows() = [<a href="#type-row">row()</a>]</tt></p>
<h3 class="typedecl"><a name="type-server_reason">server_reason()</a></h3>
<p><tt>server_reason() = {Code::integer(), SQLState::binary() | undefined, Message::binary()}</tt></p>
<h2><a name="index">Function Index</a></h2>
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#affected_rows-1">affected_rows/1</a></td><td>Returns the number of inserted, updated and deleted rows of the last
executed query or prepared statement.</td></tr>
<tr><td valign="top"><a href="#autocommit-1">autocommit/1</a></td><td>Returns true if auto-commit is enabled and false otherwise.</td></tr>
<tr><td valign="top"><a href="#change_user-3">change_user/3</a></td><td>Equivalent to <code>change_user(Conn, Username, Password, [])</code>.</td></tr>
<tr><td valign="top"><a href="#change_user-4">change_user/4</a></td><td>Changes the user of the active connection without closing and
and re-opening it.</td></tr>
<tr><td valign="top"><a href="#encode-2">encode/2</a></td><td>Encodes a term as a MySQL literal so that it can be used to inside a
query.</td></tr>
<tr><td valign="top"><a href="#execute-3">execute/3</a></td><td>Executes a prepared statement with the default query timeout as given
to start_link/1.</td></tr>
<tr><td valign="top"><a href="#execute-4">execute/4</a></td><td>Executes a prepared statement.</td></tr>
<tr><td valign="top"><a href="#execute-5">execute/5</a></td><td>Executes a prepared statement.</td></tr>
<tr><td valign="top"><a href="#in_transaction-1">in_transaction/1</a></td><td>Returns true if the connection is in a transaction and false otherwise.</td></tr>
<tr><td valign="top"><a href="#insert_id-1">insert_id/1</a></td><td>Returns the last insert-id.</td></tr>
<tr><td valign="top"><a href="#prepare-2">prepare/2</a></td><td>Creates a prepared statement from the passed query.</td></tr>
<tr><td valign="top"><a href="#prepare-3">prepare/3</a></td><td>Creates a prepared statement from the passed query and associates it
with the given name.</td></tr>
<tr><td valign="top"><a href="#query-2">query/2</a></td><td>Executes a plain query.</td></tr>
<tr><td valign="top"><a href="#query-3">query/3</a></td><td>Executes a query.</td></tr>
<tr><td valign="top"><a href="#query-4">query/4</a></td><td>Executes a query.</td></tr>
<tr><td valign="top"><a href="#query-5">query/5</a></td><td>Executes a query.</td></tr>
<tr><td valign="top"><a href="#reset_connection-1">reset_connection/1</a></td><td></td></tr>
<tr><td valign="top"><a href="#start_link-1">start_link/1</a></td><td>Starts a connection gen_server process and connects to a database.</td></tr>
<tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr>
<tr><td valign="top"><a href="#stop-2">stop/2</a></td><td>Stops a connection process and closes the connection.</td></tr>
<tr><td valign="top"><a href="#transaction-2">transaction/2</a></td><td>This function executes the functional object Fun as a transaction.</td></tr>
<tr><td valign="top"><a href="#transaction-3">transaction/3</a></td><td>This function executes the functional object Fun as a transaction.</td></tr>
<tr><td valign="top"><a href="#transaction-4">transaction/4</a></td><td>This function executes the functional object Fun with arguments Args as
a transaction.</td></tr>
<tr><td valign="top"><a href="#unprepare-2">unprepare/2</a></td><td>Deallocates a prepared statement.</td></tr>
<tr><td valign="top"><a href="#warning_count-1">warning_count/1</a></td><td>Returns the number of warnings generated by the last query/2 or
execute/3 calls.</td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
<h3 class="function"><a name="affected_rows-1">affected_rows/1</a></h3>
<div class="spec">
<p><tt>affected_rows(Conn::<a href="#type-connection">connection()</a>) -> integer()</tt><br></p>
</div><p>Returns the number of inserted, updated and deleted rows of the last
executed query or prepared statement. If found_rows is set on the
connection, for update operation the return value will equal to the number
of rows matched by the query.</p>
<h3 class="function"><a name="autocommit-1">autocommit/1</a></h3>
<div class="spec">
<p><tt>autocommit(Conn::<a href="#type-connection">connection()</a>) -> boolean()</tt><br></p>
</div><p>Returns true if auto-commit is enabled and false otherwise.</p>
<h3 class="function"><a name="change_user-3">change_user/3</a></h3>
<div class="spec">
<p><tt>change_user(Conn, Username, Password) -> Result</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Username = iodata()</tt></li><li><tt>Password = iodata()</tt></li><li><tt>Result = ok</tt></li></ul></p>
</div><p>Equivalent to <code>change_user(Conn, Username, Password, [])</code>.</p>
<p><b>See also:</b> <a href="#change_user-4">change_user/4</a>.</p>
<h3 class="function"><a name="change_user-4">change_user/4</a></h3>
<div class="spec">
<p><tt>change_user(Conn, Username, Password, Options) -> Result</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Username = iodata()</tt></li><li><tt>Password = iodata()</tt></li><li><tt>Options = [Option]</tt></li><li><tt>Result = ok</tt></li><li><tt>Option = {database, iodata()} | {queries, [iodata()]} | {prepare, [NamedStatement]}</tt></li><li><tt>NamedStatement = {StatementName::atom(), Statement::iodata()}</tt></li></ul></p>
</div><p><p>Changes the user of the active connection without closing and
and re-opening it. The currently active session will be reset (ie,
user variables, temporary tables, prepared statements, etc will
be lost) independent of whether the operation succeeds or fails.</p>
<p>If change user is called when a transaction is active (ie, neither
committed nor rolled back), calling <code>change_user</code> will fail with
an error exception and <code>change_user_in_transaction</code> as the error
message.</p>
<p>If the change user operation fails, <code>{error, Reason}</code> will be
returned. Specifically, if the operation itself fails (eg
authentication failure), <code>change_user_failed</code> will be returned as
the reason, while if the operation itself succeeds but one of
the given initial queries or prepares fails, the reason will
reflect the cause for the failure. In any case, the connection
process will exit with the same reason and cannot be used any longer.</p>
For a description of the <code>database</code>, <code>queries</code> and <code>prepare</code>
options, see <code>start_link/1</code>.
</p>
<p><b>See also:</b> <a href="#start_link-1">start_link/1</a>.</p>
<h3 class="function"><a name="encode-2">encode/2</a></h3>
<div class="spec">
<p><tt>encode(Conn::<a href="#type-connection">connection()</a>, Term::term()) -> iodata()</tt><br></p>
</div><p><p>Encodes a term as a MySQL literal so that it can be used to inside a
query. If backslash escapes are enabled, backslashes and single quotes in
strings and binaries are escaped. Otherwise only single quotes are escaped.</p>
Note that the preferred way of sending values is by prepared statements or
parametrized queries with placeholders.
</p>
<p><b>See also:</b> <a href="#execute-3">execute/3</a>, <a href="#query-3">query/3</a>.</p>
<h3 class="function"><a name="execute-3">execute/3</a></h3>
<div class="spec">
<p><tt>execute(Conn, StatementRef, Params) -> Result | {error, not_prepared}</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>StatementRef = atom() | integer()</tt></li><li><tt>Params = [term()]</tt></li><li><tt>Result = <a href="#type-query_result">query_result()</a></tt></li></ul></p>
</div><p>Executes a prepared statement with the default query timeout as given
to start_link/1.</p>
<p><b>See also:</b> <a href="#execute-5">execute/5</a>, <a href="#prepare-2">prepare/2</a>, <a href="#prepare-3">prepare/3</a>, <a href="#prepare-4">prepare/4</a>.</p>
<h3 class="function"><a name="execute-4">execute/4</a></h3>
<div class="spec">
<p><tt>execute(Conn, StatementRef, Params, Timeout::FilterMap | Timeout) -> Result | {error, not_prepared}</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>StatementRef = atom() | integer()</tt></li><li><tt>Params = [term()]</tt></li><li><tt>FilterMap = no_filtermap_fun | <a href="#type-query_filtermap_fun">query_filtermap_fun()</a></tt></li><li><tt>Timeout = default_timeout | timeout()</tt></li><li><tt>Result = <a href="#type-query_result">query_result()</a></tt></li></ul></p>
</div><p>Executes a prepared statement.</p>
<p><b>See also:</b> <a href="#execute-5">execute/5</a>, <a href="#prepare-2">prepare/2</a>, <a href="#prepare-3">prepare/3</a>, <a href="#prepare-4">prepare/4</a>.</p>
<h3 class="function"><a name="execute-5">execute/5</a></h3>
<div class="spec">
<p><tt>execute(Conn, StatementRef, Params, FilterMap, Timeout) -> Result | {error, not_prepared}</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>StatementRef = atom() | integer()</tt></li><li><tt>Params = [term()]</tt></li><li><tt>FilterMap = no_filtermap_fun | <a href="#type-query_filtermap_fun">query_filtermap_fun()</a></tt></li><li><tt>Timeout = default_timeout | timeout()</tt></li><li><tt>Result = <a href="#type-query_result">query_result()</a></tt></li></ul></p>
</div><p><p>Executes a prepared statement.</p>
The <code>FilterMap</code> and <code>Timeout</code> arguments are optional.
<ul>
<li>If the <code>FilterMap</code> argument is the atom <code>no_filtermap_fun</code> or is
omitted, no row filtering/mapping will be applied and all result rows
will be returned unchanged.</li>
<li>If the <code>Timeout</code> argument is the atom <code>default_timeout</code> or is omitted,
the timeout given in <code>start_link/1</code> is used.</li>
</ul>
See <code>query/5</code> for an explanation of the <code>FilterMap</code> argument.
</p>
<p><b>See also:</b> <a href="#prepare-2">prepare/2</a>, <a href="#prepare-3">prepare/3</a>, <a href="#prepare-4">prepare/4</a>, <a href="#query-5">query/5</a>.</p>
<h3 class="function"><a name="in_transaction-1">in_transaction/1</a></h3>
<div class="spec">
<p><tt>in_transaction(Conn::<a href="#type-connection">connection()</a>) -> boolean()</tt><br></p>
</div><p>Returns true if the connection is in a transaction and false otherwise.
This works regardless of whether the transaction has been started using
transaction/2,3 or using a plain <code>mysql:query(Connection, "BEGIN")</code>.</p>
<p><b>See also:</b> <a href="#transaction-2">transaction/2</a>, <a href="#transaction-4">transaction/4</a>.</p>
<h3 class="function"><a name="insert_id-1">insert_id/1</a></h3>
<div class="spec">
<p><tt>insert_id(Conn::<a href="#type-connection">connection()</a>) -> integer()</tt><br></p>
</div><p>Returns the last insert-id.</p>
<h3 class="function"><a name="prepare-2">prepare/2</a></h3>
<div class="spec">
<p><tt>prepare(Conn, Query) -> {ok, StatementId} | {error, Reason}</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Query = iodata()</tt></li><li><tt>StatementId = integer()</tt></li><li><tt>Reason = <a href="#type-server_reason">server_reason()</a></tt></li></ul></p>
</div><p>Creates a prepared statement from the passed query.</p>
<p><b>See also:</b> <a href="#prepare-3">prepare/3</a>.</p>
<h3 class="function"><a name="prepare-3">prepare/3</a></h3>
<div class="spec">
<p><tt>prepare(Conn, Name, Query) -> {ok, Name} | {error, Reason}</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Name = atom()</tt></li><li><tt>Query = iodata()</tt></li><li><tt>Reason = <a href="#type-server_reason">server_reason()</a></tt></li></ul></p>
</div><p>Creates a prepared statement from the passed query and associates it
with the given name.</p>
<p><b>See also:</b> <a href="#prepare-2">prepare/2</a>.</p>
<h3 class="function"><a name="query-2">query/2</a></h3>
<div class="spec">
<p><tt>query(Conn, Query) -> Result</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Query = iodata()</tt></li><li><tt>Result = <a href="#type-query_result">query_result()</a></tt></li></ul></p>
</div><p>Executes a plain query.</p>
<p><b>See also:</b> <a href="#query-5">query/5</a>.</p>
<h3 class="function"><a name="query-3">query/3</a></h3>
<div class="spec">
<p><tt>query(Conn, Query, Params::Params | FilterMap | Timeout) -> Result</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Query = iodata()</tt></li><li><tt>Timeout = default_timeout | timeout()</tt></li><li><tt>Params = no_params | [term()]</tt></li><li><tt>FilterMap = no_filtermap_fun | <a href="#type-query_filtermap_fun">query_filtermap_fun()</a></tt></li><li><tt>Result = <a href="#type-query_result">query_result()</a></tt></li></ul></p>
</div><p>Executes a query.</p>
<p><b>See also:</b> <a href="#query-5">query/5</a>.</p>
<h3 class="function"><a name="query-4">query/4</a></h3>
<div class="spec">
<p><tt>query(Conn, Query, Params, Timeout) -> Result</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Query = iodata()</tt></li><li><tt>Timeout = default_timeout | timeout()</tt></li><li><tt>Params = no_params | [term()]</tt></li><li><tt>Result = <a href="#type-query_result">query_result()</a></tt></li></ul></p>
</div><p>Executes a query.</p>
<p><b>See also:</b> <a href="#query-5">query/5</a>.</p>
<h3 class="function"><a name="query-5">query/5</a></h3>
<div class="spec">
<p><tt>query(Conn, Query, Params, FilterMap, Timeout) -> Result</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Query = iodata()</tt></li><li><tt>Timeout = default_timeout | timeout()</tt></li><li><tt>Params = no_params | [term()]</tt></li><li><tt>FilterMap = no_filtermap_fun | <a href="#type-query_filtermap_fun">query_filtermap_fun()</a></tt></li><li><tt>Result = <a href="#type-query_result">query_result()</a></tt></li></ul></p>
</div><p><p>Executes a query.</p>
<h4><a name="Parameters">Parameters</a></h4>
<p><code>Conn</code> is identifying a connection process started using
<code>mysql:start_link/1</code>.</p>
<p><code>Query</code> is the query to execute, as a binary or a list.</p>
<p><code>Params</code>, <code>FilterMap</code> and <code>Timeout</code> are optional.</p>
<p>If <code>Params</code> (a list) is specified, the query is performed as a prepared
statement. A prepared statement is created, executed and then cached for a
certain time (specified using the option <code>{query_cache_time, Milliseconds}</code>
to <code>start_link/1</code>). If the same query is executed again during this time,
it does not need to be prepared again. If <code>Params</code> is omitted (or specified
as <code>no_params</code>), the query is executed as a plain query. To force a query
without parameters to be executed as a prepared statement, an empty list can
be used for <code>Params</code>.</p>
<p>If <code>FilterMap</code> (a fun) is specified, the function is applied to each row to
filter or perform other actions on the rows, in a way similar to how
<code>lists:filtermap/2</code> works, before the result is returned to the caller. See
below for details.</p>
<p><code>Timeout</code> specifies the time to wait for a response from the database. If
omitted (or specified as <code>default_timeout</code>), the timeout given in
<code>start_link/1</code> is used.</p>
<h4><a name="Return_value">Return value</a></h4>
<p>Results are returned in the form <code>{ok, ColumnNames, Rows}</code> if there is one
result set. If there are more than one result sets, they are returned in the
form <code>{ok, [{ColumnNames, Rows}, ...]}</code>. This is typically the case if
multiple queries are specified at the same time, separated by semicolons.</p>
<p>For queries that don't return any rows (INSERT, UPDATE, etc.) only the atom
<code>ok</code> is returned.</p>
<h4><a name="FilterMap_details">FilterMap details</a></h4>
<p>If the <code>FilterMap</code> argument is used, it must be a function of arity 1 or 2
that returns either <code>true</code>, <code>false</code>, or <code>{true, Value}</code>.</p>
<p>Each result row is handed to the given function as soon as it is received
from the server, and only when the function has returned, the next row is
fetched. This provides the ability to prevent memory exhaustion. On the
other hand, it can cause the server to time out on sending if your function
is doing something slow (see the MySQL documentation on <code>NET_WRITE_TIMEOUT</code>).</p>
<p>If the function is of arity 1, only the row is passed to it as the single
argument, while if the function is of arity 2, the column names are passed
in as the first argument and the row as the second.</p>
<p>The value returned is then used to decide if the row is to be included in
the result(s) returned from the <code>query</code> call (filtering), or if something
else is to be included in the result instead (mapping). You may also use
this function for side effects, like writing rows to disk or sending them
to another process etc.</p>
<h4><a name="Examples">Examples</a></h4>
Here is an example showing some of the things that are possible:
<pre> Query = "SELECT a, b, c FROM foo",
FilterMap = fun
%% Include all rows where the first column is < 10.
([A|_]) when A < 10 ->
true;
%% Exclude all rows where the first column is >= 10 and < 20.
([A|_]) when A < 20 ->
false;
%% For rows where the first column is >= 20 and < 30, include
%% the atom 'foo' in place of the row instead.
([A|_]) when A < 30 ->
{true, foo}};
%% For rows where the first row is >= 30 and < 40, send the
%% row to a gen_server via call (ie, wait for a response),
%% and do not include the row in the result.
(R=[A|_]) when A < 40 ->
gen_server:call(Pid, R),
false;
%% For rows where the first column is >= 40 and < 50, send the
%% row to a gen_server via cast (ie, do not wait for a reply),
%% and include the row in the result, also.
(R=[A|_]) when A < 50 ->
gen_server:cast(Pid, R),
true;
%% Exclude all other rows from the result.
(_) ->
false
end,
query(Conn, Query, no_params, FilterMap, default_timeout).</pre></p>
<h3 class="function"><a name="reset_connection-1">reset_connection/1</a></h3>
<div class="spec">
<p><tt>reset_connection(Conn) -> ok | {error, Reason}</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Reason = <a href="#type-server_reason">server_reason()</a></tt></li></ul></p>
</div>
<h3 class="function"><a name="start_link-1">start_link/1</a></h3>
<div class="spec">
<p><tt>start_link(Options) -> {ok, pid()} | ignore | {error, term()}</tt>
<ul class="definitions"><li><tt>Options = [Option]</tt></li><li><tt>Option = {name, ServerName} | {host, <a href="inet.html#type-socket_address">inet:socket_address()</a> | <a href="inet.html#type-hostname">inet:hostname()</a>} | {port, integer()} | {user, iodata()} | {password, iodata()} | {database, iodata()} | {connect_mode, synchronous | asynchronous | lazy} | {connect_timeout, timeout()} | {log_warnings, boolean()} | {log_slow_queries, boolean()} | {keep_alive, boolean() | timeout()} | {prepare, NamedStatements} | {queries, [iodata()]} | {query_timeout, timeout()} | {found_rows, boolean()} | {query_cache_time, non_neg_integer()} | {tcp_options, [<a href="gen_tcp.html#type-connect_option">gen_tcp:connect_option()</a>]} | {ssl, term()}</tt></li><li><tt>ServerName = {local, Name::atom()} | {global, GlobalName::term()} | {via, Module::atom(), ViaName::term()}</tt></li><li><tt>NamedStatements = [{StatementName::atom(), Statement::iodata()}]</tt></li></ul></p>
</div><p><p>Starts a connection gen_server process and connects to a database. To
disconnect use <code>mysql:stop/1,2</code>.</p>
<p>Options:</p>
<dl>
<dt><code>{name, ServerName}</code></dt>
<dd>If a name is provided, the gen_server will be registered with this
name. For details see the documentation for the first argument of
gen_server:start_link/4.</dd>
<dt><code>{host, Host}</code></dt>
<dd>Hostname of the MySQL database. Since OTP version 19, it is also
possible to specify a local (Unix) Socket by specifying
<code>{local, SocketFile}</code>. Default <code>"localhost"</code>.</dd>
<dt><code>{port, Port}</code></dt>
<dd>Port; default 3306 for non-local or 0 for local (Unix) sockets.</dd>
<dt><code>{user, User}</code></dt>
<dd>Username.</dd>
<dt><code>{password, Password}</code></dt>
<dd>Password.</dd>
<dt><code>{database, Database}</code></dt>
<dd>The name of the database AKA schema to use. This can be changed later
using the query <code>USE <database></code>.</dd>
<dt><code>{connect_mode, synchronous | asynchronous | lazy}</code></dt>
<dd>Specifies how and when the connection process should establish a connection
to the MySQL server.
<dl>
<dt><code>synchronous</code> (default)</dt>
<dd>The connection will be established as part of the connection process'
start routine, ie the returned connection process will already be
connected and ready to use, and any on-connect prepares and queries
will have been executed.</dd>
<dt><code>asynchronous</code></dt>
<dd>The connection process will be started and returned to the caller
before really establishing a connection to the server and executing
the on-connect prepares and executes. This will instead be done
immediately afterwards as the first action of the connection
process.</dd>
<dt><code>lazy</code></dt>
<dd>Similar to <code>asynchronous</code> mode, but an actual connection will be
established and the on-connect prepares and queries executed only
when a connection is needed for the first time, eg. to execute a
query.</dd>
</dl>
</dd>
<dt><code>{connect_timeout, Timeout}</code></dt>
<dd>The maximum time to spend for start_link/1.</dd>
<dt><code>{log_warnings, boolean()}</code></dt>
<dd>Whether to fetch warnings and log them using error_logger; default
true.</dd>
<dt><code>{log_slow_queries, boolean()}</code></dt>
<dd>Whether to log slow queries using error_logger; default false. Queries
are flagged as slow by the server if their execution time exceeds the
value in the <code>long_query_time</code> variable.</dd>
<dt><code>{keep_alive, boolean() | timeout()}</code></dt>
<dd>Send ping when unused for a certain time. Possible values are <code>true</code>,
<code>false</code> and <code>integer() > 0</code> for an explicit interval in milliseconds.
The default is <code>false</code>. For <code>true</code> a default ping timeout is used.
</dd>
<dt><code>{prepare, NamedStatements}</code></dt>
<dd>Named prepared statements to be created as soon as the connection is
ready.</dd>
<dt><code>{queries, Queries}</code></dt>
<dd>Queries to be executed as soon as the connection is ready. Any results
are discarded. Typically, this is used for setting time zone and other
session variables.</dd>
<dt><code>{query_timeout, Timeout}</code></dt>
<dd>The default time to wait for a response when executing a query or a
prepared statement. This can be given per query using <code>query/3,4</code> and
<code>execute/4</code>. The default is <code>infinity</code>.</dd>
<dt><code>{found_rows, boolean()}</code></dt>
<dd>If set to true, the connection will be established with
CLIENT_FOUND_ROWS capability. affected_rows/1 will now return the
number of found rows, not the number of rows changed by the
query.</dd>
<dt><code>{query_cache_time, Timeout}</code></dt>
<dd>The minimum number of milliseconds to cache prepared statements used
for parametrized queries with query/3.</dd>
<dt><code>{tcp_options, Options}</code></dt>
<dd>Additional options for <code>gen_tcp:connect/3</code>. You may want to set
<code>{recbuf, Size}</code> and <code>{sndbuf, Size}</code> if you send or receive more than
the default (typically 8K) per query.</dd>
<dt><code>{ssl, Options}</code></dt>
<dd>Additional options for <code>ssl:connect/3</code>.</dd>
</dl></p>
<h3 class="function"><a name="stop-1">stop/1</a></h3>
<div class="spec">
<p><tt>stop(Conn) -> ok</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li></ul></p>
</div>
<p><b>See also:</b> <a href="#stop-2">stop/2</a>.</p>
<h3 class="function"><a name="stop-2">stop/2</a></h3>
<div class="spec">
<p><tt>stop(Conn, Timeout) -> ok</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>Timeout = timeout()</tt></li></ul></p>
</div><p><p>Stops a connection process and closes the connection. The
process calling <code>stop</code> will be blocked until the connection
process stops or the given timeout expires.</p>
<p>If the connection is not stopped within the given timeout,
an exit exception is raised with reason <code>timeout</code>.</p>
If the connection process exits with any other reason than <code>normal</code>,
an exit exception is raised with that reason.</p>
<h3 class="function"><a name="transaction-2">transaction/2</a></h3>
<div class="spec">
<p><tt>transaction(Conn::<a href="#type-connection">connection()</a>, Fun::function()) -> {atomic, term()} | {aborted, term()}</tt><br></p>
</div><p>This function executes the functional object Fun as a transaction.</p>
<p><b>See also:</b> <a href="#transaction-4">transaction/4</a>.</p>
<h3 class="function"><a name="transaction-3">transaction/3</a></h3>
<div class="spec">
<p><tt>transaction(Conn::<a href="#type-connection">connection()</a>, Fun::function(), Retries) -> {atomic, term()} | {aborted, term()}</tt>
<ul class="definitions"><li><tt>Retries = non_neg_integer() | infinity</tt></li></ul></p>
</div><p>This function executes the functional object Fun as a transaction.</p>
<p><b>See also:</b> <a href="#transaction-4">transaction/4</a>.</p>
<h3 class="function"><a name="transaction-4">transaction/4</a></h3>
<div class="spec">
<p><tt>transaction(Conn::<a href="#type-connection">connection()</a>, Fun::function(), Args::list(), Retries) -> {atomic, term()} | {aborted, term()}</tt>
<ul class="definitions"><li><tt>Retries = non_neg_integer() | infinity</tt></li></ul></p>
</div><p><p>This function executes the functional object Fun with arguments Args as
a transaction.</p>
<p>The semantics are as close as possible to mnesia's transactions. Transactions
can be nested and are restarted automatically when deadlocks are detected.
MySQL's savepoints are used to implement nested transactions.</p>
<p>Fun must be a function and Args must be a list of the same length as the
arity of Fun.</p>
<p>If an exception occurs within Fun, the exception is caught and <code>{aborted,
Reason}</code> is returned. The value of <code>Reason</code> depends on the class of the
exception.</p>
<p>Note that an error response from a query does not cause a transaction to be
rollbacked. To force a rollback on a MySQL error you can trigger a <code>badmatch</code>
using e.g. <code>ok = mysql:query(Pid, "SELECT some_non_existent_value")</code>. An
exception to this is the error 1213 "Deadlock", after the specified number
of retries, all failed. In this case, the transaction is aborted and the
error is retured as the reason for the aborted transaction, along with a
stacktrace pointing to where the last deadlock was detected. (In earlier
versions, up to and including 1.3.2, transactions where automatically
restarted also for the error 1205 "Lock wait timeout". This is no longer the
case.)</p>
<p>Some queries such as ALTER TABLE cause an *implicit commit* on the server.
If such a query is executed within a transaction, an error on the form
<code>{implicit_commit, Query}</code> is raised. This means that the transaction has
been committed prematurely. This also happens if an explicit COMMIT is
executed as a plain query within a managed transaction. (Don't do that!)</p>
<table>
<thead>
<tr><th>Class of exception</th><th>Return value</th></tr>
</thead>
<tbody>
<tr>
<td><code>error</code> with reason <code>ErrorReason</code></td>
<td><code>{aborted, {ErrorReason, Stack}}</code></td>
</tr>
<tr><td><code>exit(Term)</code></td><td><code>{aborted, Term}</code></td></tr>
<tr><td><code>throw(Term)</code></td><td><code>{aborted, {throw, Term}}</code></td></tr>
</tbody>
</table></p>
<h3 class="function"><a name="unprepare-2">unprepare/2</a></h3>
<div class="spec">
<p><tt>unprepare(Conn, StatementRef) -> ok | {error, Reason}</tt>
<ul class="definitions"><li><tt>Conn = <a href="#type-connection">connection()</a></tt></li><li><tt>StatementRef = atom() | integer()</tt></li><li><tt>Reason = <a href="#type-server_reason">server_reason()</a> | not_prepared</tt></li></ul></p>
</div><p>Deallocates a prepared statement.</p>
<h3 class="function"><a name="warning_count-1">warning_count/1</a></h3>
<div class="spec">
<p><tt>warning_count(Conn::<a href="#type-connection">connection()</a>) -> integer()</tt><br></p>
</div><p>Returns the number of warnings generated by the last query/2 or
execute/3 calls.</p>
<hr>
<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
<p><i>Generated by EDoc</i></p>
</body>
</html>