Packages

mysql_client

1.2.8
1.2.8

MySQL native client is written in Erlang and provides API that is very close to Connector/C library.

HexDocs

Current section

Files

Jump to
Readme
1 Version
1 Dependency
1 Dependant
Files
Activity
mysql_client doc datasource.html
Raw

doc/datasource.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 datasource</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 datasource</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>
  Datasource module implements API to manage datasource process.
<p>Copyright © 2010-2014 Alexei Krasnopolski</p>
<p><b>Version:</b> 1.2.8</p>
<p><b>Introduced in:</b> 2012-12-18</p>
<p><b>Authors:</b> Alexei Krasnopolski (<a href="mailto:krasnop@bellsouth.net"><tt>krasnop@bellsouth.net</tt></a>) [<em>web site:</em> <tt><a href="http://krasnopolski.org/" target="_top">http://krasnopolski.org/</a></tt>].</p>
<h2><a name="description">Description</a></h2>
  Datasource module implements API to manage datasource process. The process keeps information
  about given datasource and controlls a pool of connections to DS. A functions get_connection/1,
  return_connection/2 and invalidate_connection/2 directly delegate calls to the connection pool that creates/reuses/disposes
  a connections. We can think about datasource module as a wrapper for resource_pool_srv module.
 
<h2><a name="types">Data Types</a></h2>
<h3 class="typedecl"><a name="type-client_options">client_options()</a></h3>
<p><tt>client_options() = #client_options{}</tt></p>
<p>The record keeps client options that server is capable to support for this client and this connection.<br>
  -record(<strong>client_options</strong>, {
  <dl>
    <dt>charset_number = 33::0..255</dt><dd>- Character set number: default utf-8 (code= 33).</dd>
    <dt>long_password = 1::0|1</dt><dd>- new more secure passwords.</dd>
    <dt>found_rows  = 0::0|1</dt><dd>- Found instead of affected rows.</dd>
    <dt>long_flag = 1::0|1</dt><dd>- Get all column flags.</dd>
    <dt>connect_with_db = 1::0|1</dt><dd>- One can specify db on connect.</dd>
    <dt>no_schema = 0::0|1</dt><dd>- Don't allow database.table.column.</dd>
    <dt>compress = 0::0|1</dt><dd>- Can use compression protocol.</dd>
    <dt>odbc = 0::0|1</dt><dd>- Odbc client.</dd>
    <dt>local_files = 0::0|1</dt><dd>- Can use LOAD DATA LOCAL.</dd>
    <dt>ignore_space = 0::0|1</dt><dd>- Ignore spaces before '('.</dd>
    <dt>protocol_41 = 1::0|1</dt><dd>- New 4.1 protocol.</dd>
    <dt>interactive = 1::0|1</dt><dd>- This is an interactive client.</dd>
    <dt>ssl = 0::0|1</dt><dd>- Switch to SSL after handshake.</dd>
    <dt>ignore_sigpipe = 0::0|1</dt><dd>- IGNORE sigpipes.</dd>
    <dt>transactions  = 1::0|1</dt><dd>- Client knows about transactions.</dd>
    <dt>reserved = 0::0|1</dt><dd>- Old flag for 4.1 protocol.</dd>
    <dt>secure_connection = 1::0|1</dt><dd>- New 4.1 authentication.</dd>
    <dt>multi_statements = 1::0|1</dt><dd>- Enable/disable multi-stmt support.</dd>
    <dt>multi_results = 1::0|1</dt><dd>- Enable/disable multi-results.</dd>
    <dt>trans_isolation_level = default::read_uncommitted | read_committed | repeatable_read | serializable</dt>
      <dd>- transaction isolation level.
        <ul>
          <li><strong>read_uncommitted</strong> - given session can read uncommitted updates of other session.</li>
          <li><strong>read_committed</strong> - given session can read only committed updates of other session.</li>
          <li><strong>repeatable_read</strong> - given session can read only snapshot of committed updates of other session.</li>
          <li><strong>serializable</strong> - the same as repeatable read but given session blocks own reads.</li>
        </ul>
      </dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-connection">connection()</a></h3>
<p><tt>connection() = #connection{}</tt></p>
<p>The record keeps information that helps connection server runs.<br>
  -record(<strong>connection</strong>, {
  <dl>
    <dt>socket :: port()</dt><dd>- tcp socket linked to MySQL server.</dd>
    <dt>owner :: pid()</dt><dd>- pid of process that borrows this connection from connection pool. undefined if the connection is idle.</dd>
    <dt>ds_def :: #datasource{}</dt><dd>- datasource record.</dd>
    <dt>server_info :: #server_info{}</dt><dd>- server info record.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-datasource">datasource()</a></h3>
<p><tt>datasource() = #datasource{}</tt></p>
<p>datasource record information describes connections pool.
  The information is using for creating connections of the pool.<br>
  -record(<strong>datasource</strong>, {
  <dl>
    <dt>name :: atom()</dt><dd>- datasource name.</dd>
    <dt>host = "localhost" :: string()</dt><dd>- server host name or IP.</dd>
    <dt>port = 3306 :: integer()</dt><dd>- host port number.</dd>
    <dt>database = "" :: string()</dt><dd>- database name.</dd>
    <dt>user :: string()</dt><dd>- user logon name.</dd>
    <dt>password :: string()</dt><dd>- password.</dd>
    <dt>flags = #client_options{} :: #client_options{}</dt><dd>- client options for connections of the datasource.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-eof_packet">eof_packet()</a></h3>
<p><tt>eof_packet() = #eof_packet{}</tt></p>
<p>represents end of file (EOF) packet received from server after generic query or command.<br>
  -record(<strong>eof_packet</strong>, {
  <dl>
    <dt>warning_count::integer()</dt><dd>- number of warnings.</dd>
    <dt>server_status::#server_status{}</dt><dd>- server status after query.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-error_packet">error_packet()</a></h3>
<p><tt>error_packet() = #error_packet{}</tt></p>
<p>represents ERROR packet received from server after generic query or command.<br>
  -record(<strong>error_packet</strong>, {
  <dl>
    <dt>errno::integer()</dt><dd>- MySQL error number.</dd>
    <dt>sqlstate::string()</dt><dd>- MySQL state identifire.</dd>
    <dt>message::string()</dt><dd>- error message.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-field_metadata">field_metadata()</a></h3>
<p><tt>field_metadata() = #field_metadata{}</tt></p>
<p>represents field metadata of record set.<br>
  -record(<strong>field_metadata</strong>, {
  <dl>
    <dt>catalog::string()</dt><dd>- catalog name (unused in recent versions).</dd>
    <dt>schema::string()</dt><dd>- schema (database) name.</dd>
    <dt>table::string()</dt><dd>- table name from sql query (after AS).</dd>
    <dt>origtable::string()</dt><dd>- original table name from schema.</dd>
    <dt>name::string()</dt><dd>- field name from sql query (after AS).</dd>
    <dt>origname::string()</dt><dd>- original field name from schema.</dd>
    <dt>charsetnr::integer()</dt><dd>- code of character set.</dd>
    <dt>length::integer()</dt><dd>- length of the field.</dd>
    <dt>type::0..255</dt><dd>- type of the field (see mysql_types.hrl).</dd>
    <dt>flags::bitstring()</dt><dd>- flags (see mysql_types.hrl).</dd>
    <dt>scale::0..255</dt><dd>- scale.</dd>
    <dt>default::binary()</dt><dd>- default value.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-metadata">metadata()</a></h3>
<p><tt>metadata() = #metadata{}</tt></p>
<p>represents metadata of record set.<br>
  -record(<strong>metadata</strong>, {
  <dl>
    <dt>field_count=0::integer()</dt><dd>- field count in the query.</dd>
    <dt>param_count=0::integer()</dt><dd>- parameter count in prepared statement.</dd>
    <dt>server_status::#server_status{}</dt><dd>- server status after query.</dd>
    <dt>field_metadata = []::list(#field_metadata{})</dt><dd>- field metadata is a list of metadata
  for each field in the query.</dd>
    <dt>param_metadata = []::list(#field_metadata{})</dt><dd>- parameter metadata is a list of metadata
  for each parameter in the prepared statement..</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-mysql_decimal">mysql_decimal()</a></h3>
<p><tt>mysql_decimal() = #mysql_decimal{}</tt></p>
<p>represents value of decimal field.<br>
  -record(<strong>mysql_decimal</strong>, {
  <dl>
    <dt>int = ""::string()</dt><dd>- integer part.</dd>
    <dt>fraction = ""::string()</dt><dd>- fraction part.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-mysql_error">mysql_error()</a></h3>
<p><tt>mysql_error() = #mysql_error{}</tt></p>
<p>Record represents an exception that is thrown by a client's module.<br>
  -record(<strong>mysql_error</strong>, {
  <dl>
    <dt>type:: tcp | connection | sqlquery | statement | transaction</dt><dd>- .</dd>
    <dt>errno = none:: none | integer()</dt><dd>- .</dd>
    <dt>sqlstate = []::string()</dt><dd>- .</dd>
    <dt>source = []::string()</dt><dd>- .</dd>
    <dt>message = []::string()</dt><dd>- .</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-mysql_time">mysql_time()</a></h3>
<p><tt>mysql_time() = #mysql_time{}</tt></p>
<p>represents value of time/date field.<br>
  -record(<strong>mysql_time</strong>, {
  <dl>
    <dt>neg = false::boolean()</dt><dd>- sign of the field.</dd>
    <dt>year = 0::integer()</dt><dd>- year.</dd>
    <dt>month = 0::0..12</dt><dd>- month.</dd>
    <dt>day = 0::0..31</dt><dd>- day of month.</dd>
    <dt>hour = 0::0..23</dt><dd>- hour.</dd>
    <dt>minute = 0::0..59</dt><dd>- minute.</dd>
    <dt>second = 0::0..59</dt><dd>- second.</dd>
    <dt>second_part = 0</dt><dd>- second part.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-ok_packet">ok_packet()</a></h3>
<p><tt>ok_packet() = #ok_packet{}</tt></p>
<p>represents OK packet received from server after generic query or command.<br>
  -record(<strong>ok_packet</strong>, {
  <dl>
    <dt>affected_rows::integer()</dt><dd>- number affected rows in table(s) during processing query.</dd>
    <dt>insert_id::integer()</dt><dd>- insert query returns generated id for new row.</dd>
    <dt>server_status::#server_status{}</dt><dd>- server status after query.</dd>
    <dt>warning_count::integer()</dt><dd>- number of warnings.</dd>
    <dt>message::string()</dt><dd>- warn/error message.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-ok_stmt_packet">ok_stmt_packet()</a></h3>
<p><tt>ok_stmt_packet() = #ok_stmt_packet{}</tt></p>
<p>represents OK packet received from server after statement prepare command.<br>
  -record(<strong>ok_stmt_packet</strong>, {
  <dl>
    <dt>stmt_handle::integer()</dt><dd>- prepared statement handle for using with following commands.</dd>
    <dt>columns_number::integer()</dt><dd>- number of columns in prepared statement.</dd>
    <dt>params_number::integer()</dt><dd>- number of parameters in prepared statement.</dd>
    <dt>warn_count::integer()</dt><dd>- number of warnings.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-packet">packet()</a></h3>
<p><tt>packet() = #packet{}</tt></p>
<p>represents binary packet for low level network connection.<br>
  -record(<strong>packet</strong>, {
  <dl>
    <dt>continue = false::boolean()</dt><dd>- indicates it is not last packet in sequence.</dd>
    <dt>seq_number = 0::integer()</dt><dd>- number of the packet in sequence.</dd>
    <dt>uncompressed_size = 0::integer()</dt><dd>- size of packet before compression.</dd>
    <dt>body = <code>&lt;&lt;&gt;&gt;</code>::binary()</dt><dd>- binary body of the packet.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-rs_header">rs_header()</a></h3>
<p><tt>rs_header() = #rs_header{}</tt></p>
<p>represents a header of record set.<br>
  -record(<strong>rs_header</strong>, {
  <dl>
    <dt>field_count::integer()</dt><dd>- number of fields in record set.</dd>
    <dt>extra::any()</dt><dd>- extra information.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-server_info">server_info()</a></h3>
<p><tt>server_info() = #server_info{}</tt></p>
<p>The server_info() contains information that SQL server sent during handshake about itself.
  -record(<strong>server_info</strong>, {
  <dl>
    <dt>protocol_version::integer()</dt><dd>- protocol version.</dd>
    <dt>server_version::string()</dt><dd>- server version.</dd>
    <dt>thread_Id::integer()</dt><dd>- current connection thread ID.</dd>
    <dt>server_capabilities::#client_options{}</dt><dd>- server capabilities.</dd>
    <dt>server_status::#server_status{}</dt><dd>- server status.</dd>
    <dt>scramble_buff::binary()</dt><dd>- scrumble buffer for password encryption.</dd>
  </dl>
  }).</p>
<h3 class="typedecl"><a name="type-server_status">server_status()</a></h3>
<p><tt>server_status() = #server_status{}</tt></p>
<p>The server_status() record contains information about status of SQL server after query.<br>
  -record(<strong>server_status</strong>, {
  <dl>
    <dt>inTransaction = false::boolean()</dt><dd>- Transaction has started.</dd>
    <dt>autocommit = false::boolean()</dt><dd>- Server in auto_commit mode.</dd>
    <dt>moreResultExists = false::boolean()</dt><dd>- Multi query - next query exists.</dd>
    <dt> queryNoGoodIndexUsed = false::boolean()</dt><dd>- .</dd>
    <dt>queryNoIndexUsed = false::boolean()</dt><dd>- .</dd>
    <dt>cursorExists = false::boolean()</dt><dd>- read-only non-scrollable cursor for a query was opened.</dd>
    <dt>lastRowSent = false::boolean()</dt><dd>- read-only cursor is exhausted.</dd>
    <dt>noBackSlashEscapes = true::boolean()</dt><dd>- .</dd>
    <dt>queryWasSlow = false::boolean()</dt><dd>- this query was logged to the slow query log.</dd>
    <dt>psOutParams = false::boolean()</dt><dd>- To mark ResultSet containing output parameter values.</dd>
  </dl>
  }).</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="#close-1">close/1</a></td><td>Stops datasource DS_name and disposes all linked resources.</td></tr>
<tr><td valign="top"><a href="#change_user-4">change_user/4</a></td><td>Changes user for the datasource.</td></tr>
<tr><td valign="top"><a href="#select_db-2">select_db/2</a></td><td>Selects or changes current database (or schema).</td></tr>
<tr><td valign="top"><a href="#get_connection-1">get_connection/1</a></td><td>Provides with connection process pid.</td></tr>
<tr><td valign="top"><a href="#return_connection-2">return_connection/2</a></td><td>Returns the connection to connection pool.</td></tr>
<tr><td valign="top"><a href="#invalidate_connection-2">invalidate_connection/2</a></td><td>Sends request to dispose the connection.</td></tr>
</table>
<h2><a name="functions">Function Details</a></h2>
<h3 class="function"><a name="close-1">close/1</a></h3>
<div class="spec">
<p><tt>close(DS_name::atom()) -&gt; ok | {error, Error}</tt><br></p>
<p> </p>
</div><p>Stops datasource DS_name and disposes all linked resources.
 </p>
<h3 class="function"><a name="change_user-4">change_user/4</a></h3>
<div class="spec">
<p><tt>change_user(Connection_name::pid(), User::string(), Password::string(), Db::string) -&gt; #connection{} | #mysql_error{}</tt><br></p>
<p> </p>
</div><p>Changes user for the datasource. This change concerns all
  connections of the connected datasource/pool.</p>
<p><b>See also:</b> <a href="helper_connection.html#change_user-4">helper_connection:change_user/4</a>.</p>
<h3 class="function"><a name="select_db-2">select_db/2</a></h3>
<div class="spec">
<p><tt>select_db(Connection_name::pid(), DBName::string()) -&gt; Result</tt>
<ul class="definitions"><li><tt>Result = {Metadata::#metadata{}, [#ok_packet{}]} | #mysql_error{}</tt></li></ul></p>
<p> </p>
</div><p>Selects or changes current database (or schema). Change concerns all
  connections of the given datasource/pool.
 </p>
<h3 class="function"><a name="get_connection-1">get_connection/1</a></h3>
<div class="spec">
<p><tt>get_connection(DS_name::atom()) -&gt; pid() | #mysql_error{}</tt><br></p>
<p> </p>
</div><p>Provides with connection process pid. Connection pool returns idle connection or creates new
  connection process if no idle connection is found.
 </p>
<h3 class="function"><a name="return_connection-2">return_connection/2</a></h3>
<div class="spec">
<p><tt>return_connection(DS_name::atom(), Resource::pid()) -&gt; ok | #mysql_error{}</tt><br></p>
<p> </p>
</div><p>Returns the connection to connection pool.
 </p>
<h3 class="function"><a name="invalidate_connection-2">invalidate_connection/2</a></h3>
<div class="spec">
<p><tt>invalidate_connection(DS_name::atom(), Resource::pid()) -&gt; ok | #mysql_error{}</tt><br></p>
<p> </p>
</div><p>Sends request to dispose the connection.
 </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>