| Overview |  |
The main Emysql module.
- -Emysql is implemented as an Erlang - application. The term has a special meaning in Erlang, see - http://www.erlang.org/doc/design_principles/applications.html
- -This module exports functions to: -
-module(sample). - -export([run/0]). - - run() -> - - crypto:start(), - emysql:start(), - - emysql:add_pool(hello_pool, 1, - "hello_username", "hello_password", "localhost", 3306, - "hello_database", utf8), - - emysql:execute(hello_pool, - <<"INSERT INTO hello_table SET hello_text = 'Hello World!'">>), - - emysql:prepare(my_stmt, <<"SELECT * from mytable WHERE id = ?">>), - - Result = emysql:execute(mypoolname, my_stmt, [1]).- -
Under Implementation, you can find details about the -inner workings of Emysql. If you are new to Emysql, you may safely ignore -them.
- - start(), stop(), modules() and default_timeout() are one-line 'fascades': -start() -> application:start(emysql). - stop() -> application:stop(emysql). - modules() -> emysql_app:modules(). - default_timeout() -> emysql_app:default_timeout().- - execute() and prepare() are the bulk of the source - of this module. A lot gets repeated for default values in lesser arities. - The quintessential execute however is this, in execute/2: -
execute(PoolId, Query, Args, Timeout)
- when (is_list(Query) orelse is_binary(Query)) andalso is_list(Args) andalso is_integer(Timeout) ->
-
- Connection =
- emysql_conn_mgr:wait_for_connection(PoolId),
- monitor_work(Connection, Timeout, {emysql_conn, execute, [Connection, Query, Args]});-As all executions, it uses the monitor_work/3 function to create a process to -asynchronously handle the execution.
- - The pool-related functions execute brief operations using the primitive - functions exported byemysql_conn_mgr and emysql_conn_mgr.
-state() = any()
- - -| add_pool/2 | Synchronous call to the connection manager to add a pool. |
| add_pool/8 | Adds a pool using the default start commands (empty list). |
| add_pool/9 | Synchronous call to the connection manager to add a pool. |
| affected_rows/1 | affected_rows/1 extracts the number of affected rows from an OK Packet. |
| as_dict/1 | package row data as a dict. |
| as_json/1 | package row data as erlang json (jsx/jiffy compatible). |
| as_proplist/1 | package row data as a proplist. |
| as_record/3 | Equivalent to as_record(Res, Recname, Fields, fun (A) -> A end). - |
| as_record/4 | package row data as records. |
| decrement_pool_size/2 | Synchronous call to the connection manager to shrink a pool. |
| default_timeout/0 | Returns the default timeout in milliseconds. |
| execute/2 | Execute a query, prepared statement or a stored procedure. |
| execute/3 | Execute a query, prepared statement or a stored procedure. |
| execute/4 | Execute a query, prepared statement or a stored procedure. |
| execute/5 | Execute a query, prepared statement or a stored procedure - but return immediately, returning the atom 'unavailable', when no connection in the pool is readily available without wait. |
| field_names/1 | Return the field names of a result packet. |
| increment_pool_size/2 | |
| insert_id/1 | insert_id/1 extracts the Insert ID from an OK Packet. |
| prepare/2 | Prepare a statement. |
| remove_pool/1 | Synchronous call to the connection manager to remove a pool. |
| result_type/1 | result_type/1 decodes a packet into its type. |
| start/0 | Start the Emysql application. |
| stop/0 | Stop the Emysql application. |
add_pool(PoolId, Options) -> Result -
Synchronous call to the connection manager to add a pool.
- -Options:
- -size - pool size (defaults to 1) -user - user to connect with (defaults to "") -password - user password (defaults to "") -host - host to connect to (defaults to "127.0.0.1") -port - the port to connect to (defaults to 3306) -database - the database to connect to (defaults to undefined) -encoding - the connection encoding (defaults to utf8) -start_cmds - a list of commands to execute on connect -connect_timeout - millisecond timeout for connect or infinity (default)
- -add_pool(PoolId, Size, User, Password, Host, Port, Database, Encoding) -> Result
Equivalent to add_pool(PoolId, Size, User, Password, Host, Port, - Database, Encoding, []).
-Adds a pool using the default start commands (empty list). -
- -add_pool(PoolId, Size, User, Password, Host, Port, Database, Encoding, StartCmds) -> Result -
-Synchronous call to the connection manager to add a pool.
- -affected_rows(Ok_packet::#ok_packet{}) -> integer()
affected_rows/1 extracts the number of affected rows from an OK Packet
- -as_dict(Result) -> Dict -
package row data as a dict
- --module(fetch_example).
- - fetch_foo() -> - Res = emysql:execute(pool1, "select * from foo"), - Res:as_dict(Res). - -as_json(Res) -> any()
-package row data as erlang json (jsx/jiffy compatible)
- -as_proplist(Res::Result) -> proplist -
package row data as a proplist
- --module(fetch_example).
- - fetch_foo() -> - Res = emysql:execute(pool1, "select * from foo"), - Res:as_proplist(Res). - -as_record(Res, Recname, Fields) -> any()
-Equivalent to as_record(Res, Recname, Fields, fun (A) -> A end).
- - -as_record(Res::Result, Recname::RecordName, Fields, Fun) -> Result -
package row data as records
- -RecordName is the name of the record to generate. -Fields are the field names to generate for each record.
- --module(fetch_example).
- - fetch_foo() -> - Res = emysql:execute(pool1, "select * from foo"), - Res:as_record(foo, record_info(fields, foo)). - -decrement_pool_size(PoolId, Num::By) -> ok -
Synchronous call to the connection manager to shrink a pool.
- -This reduces the connections by up to n=By, but it only drops and closes available -connections that are not in use at the moment that this function is called. Connections -that are waiting for a server response are never dropped. In heavy duty, this function -may thus do nothing.
- -If 'By' is higher than the amount of connections or the amount of available connections, -exactly all available connections are dropped and closed.
- - -default_timeout() -> Timeout -
Returns the default timeout in milliseconds. As set in emysql.app.src, -or if not set, the value ?TIMEOUT as defined in include/emysql.hrl (8000ms).
- -execute(PoolId, Query::Query | StmtName) -> Result | [Result] -
Execute a query, prepared statement or a stored procedure.
- -Same as execute(PoolId, Query, [], default_timeout()).
See also: execute/3, execute/4, execute/5, prepare/2.
- -execute(PoolId, Query::Query | StmtName, Args::Args | Timeout) -> Result | [Result] -
Execute a query, prepared statement or a stored procedure.
- -Same as execute(PoolId, Query, Args, default_timeout())
- or execute(PoolId, Query, [], Timeout).
Timeout is the query timeout in milliseconds or the atom infinity.
- - The result is a list for stored procedure execution >= MySQL 4.1 - -See also: execute/2, execute/4, execute/5, prepare/2.
- -execute(PoolId, Query::Query | StmtName, Args, Timeout) -> Result | [Result] -
Execute a query, prepared statement or a stored procedure.
- - Connection = emysql_conn_mgr:wait_for_connection(PoolId),
- monitor_work(Connection, Timeout, {emysql_conn, execute, [Connection, Query_or_StmtName, Args]}).-Timeout is the query timeout in milliseconds or the atom infinity.
- - All other execute function eventually call this function. - -See also: execute/2, execute/3, execute/5, prepare/2.
- -execute(PoolId, Query::Query | StmtName, Args, Timeout, X5::nonblocking) -> Result | [Result] -
Execute a query, prepared statement or a stored procedure - but return immediately, returning the atom 'unavailable', when no connection in the pool is readily available without wait.
- -Timeout is the query timeout in milliseconds or the atom infinity.
- - {Connection, connection} = case emysql_conn_mgr:lock_connection(PoolId),
- monitor_work(Connection, Timeout, {emysql_conn, execute, [Connection, Query_or_StmtName, Args]}).
-
- The result is a list for stored procedure execution >= MySQL 4.1
- - All other execute function eventually call this function. - -See also: execute/2, execute/3, execute/4, prepare/2.
- -field_names(Result) -> [Name] -
Return the field names of a result packet
- -increment_pool_size(PoolId::atom(), Num::non_neg_integer()) -> ok | {error, list()}
insert_id(Ok_packet::#ok_packet{}) -> integer() | binary()
insert_id/1 extracts the Insert ID from an OK Packet
- -prepare(StmtName, Statement) -> ok -
Prepare a statement.
- -The atom given by parameter 'StmtName' is bound to the SQL string
- 'Statement'. Calling execute(<Pool>, StmtName, <ParamList>) executes the
- statement with parameters from <ParamList>.
This is not a mySQL prepared statement, but an implementation on the side of -Emysql.
- - -module(sample).
- -export([run/0]).
-
- run() ->
-
- application:start(sasl),
- crypto:start(),
- application:start(emysql),
-
- emysql:add_pool(hello_pool, 1,
- "hello_username", "hello_password", "localhost", 3306,
- "hello_database", utf8),
-
- emysql:execute(hello_pool,
- <<"INSERT INTO hello_table SET hello_text = 'Hello World!'">>),
-
- emysql:prepare(hello_stmt,
- <<"SELECT * from hello_table WHERE hello_text like ?">>),
-
- Result = emysql:execute(hello_pool, hello_stmt, ["Hello%"]),
-
- io:format("~n~s~n", [string:chars($-,72)]),
- io:format("~p~n", [Result]),
-
- ok.
- Output:
- {result_packet,32,
- [{field,2,<<"def">>,<<"hello_database">>,
- <<"hello_table">>,<<"hello_table">>,
- <<"hello_text">>,<<"hello_text">>,254,<<>>,33,
- 60,0,0}],
- [[<<"Hello World!">>]],
- <<>>}
- Hands parameters over to emysql_statements:add/2:
- emysql_statements:add(StmtName, Statement)., which calls
- handle_call({add, StmtName, Statement}, _From, State).
State#state{
- statements = gb_trees:enter(StmtName, {1, Statement},
- State#state.statements)
- Execution is called like this:
- execute(Connection, StmtName, Args) when is_atom(StmtName), is_list(Args) -> - prepare_statement(Connection, StmtName), - case set_params(Connection, 1, Args, undefined) of - OK when is_record(OK, ok_packet) -> - ParamNamesBin = list_to_binary(string:join([[$@ | integer_to_list(I)] || I <- lists:seq(1, length(Args))], ", ")), - StmtNameBin = atom_to_binary(StmtName, utf8), - Packet = <<?COM_QUERY, "EXECUTE ", StmtNameBin/binary, " USING ", ParamNamesBin/binary>>, - emysql_tcp:send_and_recv_packet(Connection#emysql_connection.socket, Packet, 0); - Error -> - Error - end.- -
See also: emysql_conn:execute/3, emysql_statements:add/2, emysql_statements:handle/3.
- -remove_pool(PoolId) -> ok -
Synchronous call to the connection manager to remove a pool.
- -result_type(Ok_packet) -> any()
-result_type/1 decodes a packet into its type
- -start() -> ok
Start the Emysql application.
- -Simply calls application:start(emysql).
-If the application is not already loaded, the application controller will -first load it using application:load/1. It will check the value of the -applications key, to ensure that all applications that should be started -before this application are running. The application controller then -creates an application master for the application. The application master -is the group leader of all the processes in the application. The -application master starts the application by calling the application -callback function start/2 in the module, and with the start argument, -defined by the mod key in the .app file.
- -application:start(Application) is the same as calling -application:start(Application, temporary). If a temporary application -terminates, this is reported but no other applications are terminated.
- - See http://www.erlang.org/doc/design_principles/applications.html - -stop() -> ok
Stop the Emysql application.
- -Simply calls application:stop(emysql).
-It is always possible to stop an application explicitly by calling -application:stop/1. Regardless of the mode, no other applications will be -affected.
- - See http://www.erlang.org/doc/design_principles/applications.html -Generated by EDoc, Feb 27 2014, 15:11:46.
- - diff --git a/doc/emysql_app.html b/doc/emysql_app.html deleted file mode 100644 index 3e0eb9b8..00000000 --- a/doc/emysql_app.html +++ /dev/null @@ -1,68 +0,0 @@ - - - - -Behaviours: application.
- -| conn_test_period/0 | |
| default_timeout/0 | |
| lock_timeout/0 | |
| modules/0 | |
| pools/0 | |
| start/2 | |
| stop/1 |
conn_test_period() -> any()
-default_timeout() -> any()
-lock_timeout() -> any()
-modules() -> any()
-pools() -> any()
-start(Type, StartArgs) -> any()
-stop(State) -> any()
-Generated by EDoc, Feb 27 2014, 15:11:46.
- - diff --git a/doc/emysql_conn_mgr.html b/doc/emysql_conn_mgr.html deleted file mode 100644 index 89d82a23..00000000 --- a/doc/emysql_conn_mgr.html +++ /dev/null @@ -1,152 +0,0 @@ - - - - -Behaviours: gen_server.
- -add_connections(PoolId, Conns) -> any()
-add_pool(Pool) -> any()
-code_change(OldVsn, State, Extra) -> any()
-find_pool(PoolId, Pools) -> any()
-give_manager_control(Socket) -> any()
-handle_call(X1, From, State) -> any()
-handle_cast(Msg, State) -> any()
-handle_info(Info, State) -> any()
-has_pool(Pool) -> any()
-init(X1) -> any()
-lock_connection(PoolId) -> any()
-pass_connection(Connection) -> any()
-pools() -> any()
-remove_connections(PoolId, Num) -> any()
-remove_pool(PoolId) -> any()
-replace_connection_as_available(OldConn, NewConn) -> any()
-replace_connection_as_locked(OldConn, NewConn) -> any()
-start_link() -> any()
-terminate(Reason, State) -> any()
-wait_for_connection(PoolId) -> any()
-wait_for_connection(PoolId, Timeout) -> any()
-Generated by EDoc, Feb 27 2014, 15:11:46.
- - diff --git a/doc/emysql_statements.html b/doc/emysql_statements.html deleted file mode 100644 index 56c004cb..00000000 --- a/doc/emysql_statements.html +++ /dev/null @@ -1,104 +0,0 @@ - - - - -Behaviours: gen_server.
- -| add/2 | |
| all/0 | |
| code_change/3 | |
| fetch/1 | |
| handle_call/3 | |
| handle_cast/2 | |
| handle_info/2 | |
| init/1 | |
| prepare/3 | |
| remove/1 | |
| start_link/0 | |
| terminate/2 | |
| version/2 |
add(StmtName, Statement) -> any()
-all() -> any()
-code_change(OldVsn, State, Extra) -> any()
-fetch(StmtName) -> any()
-handle_call(X1, From, State) -> any()
-handle_cast(Msg, State) -> any()
-handle_info(Info, State) -> any()
-init(X1) -> any()
-prepare(ConnId, StmtName, Version) -> any()
-remove(ConnId) -> any()
-start_link() -> any()
-terminate(Reason, State) -> any()
-version(ConnId, StmtName) -> any()
-Generated by EDoc, Feb 27 2014, 15:11:46.
- - diff --git a/doc/emysql_util.html b/doc/emysql_util.html deleted file mode 100644 index 59a7397e..00000000 --- a/doc/emysql_util.html +++ /dev/null @@ -1,80 +0,0 @@ - - - - -This module is deprecated: Please use the functions in emysql instead.
| affected_rows/1 | |
| as_dict/1 | |
| as_json/1 | |
| as_proplist/1 | |
| as_record/3 | |
| as_record/4 | |
| field_names/1 | |
| insert_id/1 | |
| result_type/1 |
affected_rows(P) -> any()
-as_dict(Res) -> any()
-as_json(Res) -> any()
-as_proplist(Res) -> any()
-as_record(Res, RecName, Fields) -> any()
-as_record(Res, RecName, Fields, Fun) -> any()
-field_names(R) -> any()
-insert_id(P) -> any()
-result_type(R) -> any()
-Generated by EDoc, Feb 27 2014, 15:11:46.
- - diff --git a/doc/emysql_worker.html b/doc/emysql_worker.html deleted file mode 100644 index d391d902..00000000 --- a/doc/emysql_worker.html +++ /dev/null @@ -1,45 +0,0 @@ - - - - -| behaviour_info/1 | |
| execute/2 | |
| start/1 |
behaviour_info(X1) -> any()
-execute(To::Pid, Message) -> Result -
start(Module) -> Result -
Generated by EDoc, Feb 27 2014, 15:11:46.
- - diff --git a/doc/index.html b/doc/index.html deleted file mode 100644 index e422ef4d..00000000 --- a/doc/index.html +++ /dev/null @@ -1,17 +0,0 @@ - - - -| emysql |
| emysql_app |
| emysql_conn_mgr |
| emysql_statements |
| emysql_util |
| emysql_worker |
Version: 0.4.1 -
-Authors: Bill Warnecke, Jacob Vorreuter, Henning Diedrich, Jesper Louis Andersen. Contributions by many others..
- -Generated by EDoc, Feb 27 2014, 15:11:46.
- - diff --git a/doc/packages-frame.html b/doc/packages-frame.html deleted file mode 100644 index a6447fba..00000000 --- a/doc/packages-frame.html +++ /dev/null @@ -1,11 +0,0 @@ - - - -