|
@@ -60,33 +60,33 @@ provide a common fork for community development.
|
|
|
+ {timeout, Integer} milliseconds, defaults to 5000
|
|
|
+ {async, Pid} see Server Notifications section
|
|
|
|
|
|
- {ok, C} = pgsql:connect("localhost", "username", [{database, "test_db"}]).
|
|
|
- ok = pgsql:close(C).
|
|
|
+ {ok, C} = pgsql:connect("localhost", "username", [{database, "test_db"}]).
|
|
|
+ ok = pgsql:close(C).
|
|
|
|
|
|
The timeout parameter will trigger an {error, timeout} result when the
|
|
|
socket fails to connect within Timeout milliseconds.
|
|
|
|
|
|
Asynchronous connect example (applies to ipgsql too):
|
|
|
|
|
|
- {ok, C} = apgsql:start_link(),
|
|
|
- Ref = apgsql:connect(C, "localhost", "username", [{database, "test_db"}]),
|
|
|
- receive
|
|
|
- {C, Ref, connected} ->
|
|
|
- {ok, C};
|
|
|
- {C, Ref, Error = {error, _}} ->
|
|
|
- Error;
|
|
|
- {'EXIT', C, _Reason} ->
|
|
|
- {error, closed}
|
|
|
- end.
|
|
|
+ {ok, C} = apgsql:start_link(),
|
|
|
+ Ref = apgsql:connect(C, "localhost", "username", [{database, "test_db"}]),
|
|
|
+ receive
|
|
|
+ {C, Ref, connected} ->
|
|
|
+ {ok, C};
|
|
|
+ {C, Ref, Error = {error, _}} ->
|
|
|
+ Error;
|
|
|
+ {'EXIT', C, _Reason} ->
|
|
|
+ {error, closed}
|
|
|
+ end.
|
|
|
|
|
|
|
|
|
* Simple Query
|
|
|
|
|
|
- {ok, Columns, Rows} = pgsql:squery(C, "select ...").
|
|
|
- {ok, Count} = pgsql:squery(C, "update ...").
|
|
|
- {ok, Count, Columns, Rows} = pgsql:squery(C, "insert ... returning ...").
|
|
|
+ {ok, Columns, Rows} = pgsql:squery(C, "select ...").
|
|
|
+ {ok, Count} = pgsql:squery(C, "update ...").
|
|
|
+ {ok, Count, Columns, Rows} = pgsql:squery(C, "insert ... returning ...").
|
|
|
|
|
|
- {error, Error} = pgsql:squery(C, "invalid SQL").
|
|
|
+ {error, Error} = pgsql:squery(C, "invalid SQL").
|
|
|
|
|
|
Columns - list of column records, see pgsql.hrl for definition.
|
|
|
Rows - list of tuples, one for each row.
|
|
@@ -97,50 +97,50 @@ provide a common fork for community development.
|
|
|
|
|
|
Several queries separated by semicolon can be executed by squery.
|
|
|
|
|
|
- [{ok, _, [{<<"1">>}]}, {ok, _, [{<<"2">>}]}] =
|
|
|
- pgsql:squery(C, "select 1; select 2").
|
|
|
+ [{ok, _, [{<<"1">>}]}, {ok, _, [{<<"2">>}]}] =
|
|
|
+ pgsql:squery(C, "select 1; select 2").
|
|
|
|
|
|
apgsql:squery returns result as a single message:
|
|
|
|
|
|
- Ref = apgsql:squery(C, Sql),
|
|
|
- receive
|
|
|
- {C, Ref, Result} -> Result
|
|
|
- end.
|
|
|
+ Ref = apgsql:squery(C, Sql),
|
|
|
+ receive
|
|
|
+ {C, Ref, Result} -> Result
|
|
|
+ end.
|
|
|
|
|
|
Result has same format as return value of pgsql:squery.
|
|
|
|
|
|
ipgsql:squery returns results incrementally for each query inside Sql and
|
|
|
for each row:
|
|
|
|
|
|
- Ref = ipgsql:squery(C, Sql),
|
|
|
- receive
|
|
|
- {C, Ref, {columns, Columns}} ->
|
|
|
- %% columns description
|
|
|
- Columns;
|
|
|
- {C, Ref, {data, Row}} ->
|
|
|
- %% single data row
|
|
|
- Row;
|
|
|
- {C, Ref, {error, _E} = Error} ->
|
|
|
- Error;
|
|
|
- {C, Ref, {complete, {_Type, Count}}} ->
|
|
|
- %% execution of one insert/update/delete has finished
|
|
|
- {ok, Count}; % affected rows count
|
|
|
- {C, Ref, {complete, _Type}} ->
|
|
|
- %% execution of one select has finished
|
|
|
- ok;
|
|
|
- {C, Ref, done} ->
|
|
|
- %% execution of all queries from Sql has finished
|
|
|
- done;
|
|
|
- end.
|
|
|
+ Ref = ipgsql:squery(C, Sql),
|
|
|
+ receive
|
|
|
+ {C, Ref, {columns, Columns}} ->
|
|
|
+ %% columns description
|
|
|
+ Columns;
|
|
|
+ {C, Ref, {data, Row}} ->
|
|
|
+ %% single data row
|
|
|
+ Row;
|
|
|
+ {C, Ref, {error, _E} = Error} ->
|
|
|
+ Error;
|
|
|
+ {C, Ref, {complete, {_Type, Count}}} ->
|
|
|
+ %% execution of one insert/update/delete has finished
|
|
|
+ {ok, Count}; % affected rows count
|
|
|
+ {C, Ref, {complete, _Type}} ->
|
|
|
+ %% execution of one select has finished
|
|
|
+ ok;
|
|
|
+ {C, Ref, done} ->
|
|
|
+ %% execution of all queries from Sql has finished
|
|
|
+ done;
|
|
|
+ end.
|
|
|
|
|
|
|
|
|
* Extended Query
|
|
|
|
|
|
- {ok, Columns, Rows} = pgsql:equery(C, "select ...", [Parameters]).
|
|
|
- {ok, Count} = pgsql:equery(C, "update ...", [Parameters]).
|
|
|
- {ok, Count, Columns, Rows} = pgsql:equery(C, "insert ... returning ...", [Parameters]).
|
|
|
+ {ok, Columns, Rows} = pgsql:equery(C, "select ...", [Parameters]).
|
|
|
+ {ok, Count} = pgsql:equery(C, "update ...", [Parameters]).
|
|
|
+ {ok, Count, Columns, Rows} = pgsql:equery(C, "insert ... returning ...", [Parameters]).
|
|
|
|
|
|
- {error, Error} = pgsql:equery(C, "invalid SQL", [Parameters]).
|
|
|
+ {error, Error} = pgsql:equery(C, "invalid SQL", [Parameters]).
|
|
|
|
|
|
Parameters - optional list of values to be bound to $1, $2, $3, etc.
|
|
|
|
|
@@ -157,10 +157,10 @@ provide a common fork for community development.
|
|
|
|
|
|
Asynchronous api equery requires you to parse statement beforehand
|
|
|
|
|
|
- Ref = apgsql:equery(C, Statement, [Parameters]),
|
|
|
- receive
|
|
|
- {C, Ref, Res} -> Res
|
|
|
- end.
|
|
|
+ Ref = apgsql:equery(C, Statement, [Parameters]),
|
|
|
+ receive
|
|
|
+ {C, Ref, Res} -> Res
|
|
|
+ end.
|
|
|
|
|
|
Statement - parsed statement (see parse below)
|
|
|
Res has same format as return value of pgsql:equery.
|
|
@@ -171,7 +171,7 @@ provide a common fork for community development.
|
|
|
|
|
|
* Parse/Bind/Execute
|
|
|
|
|
|
- {ok, Statement} = pgsql:parse(C, [StatementName], Sql, [ParameterTypes]).
|
|
|
+ {ok, Statement} = pgsql:parse(C, [StatementName], Sql, [ParameterTypes]).
|
|
|
|
|
|
StatementName - optional, reusable, name for the prepared statement.
|
|
|
ParameterTypes - optional list of PostgreSQL types for each parameter.
|
|
@@ -181,20 +181,20 @@ provide a common fork for community development.
|
|
|
apgsql:parse sends {C, Ref, {ok, Statement} | {error, Reason}}.
|
|
|
ipgsql:parse sends:
|
|
|
|
|
|
- {C, Ref, {types, Types}}
|
|
|
- {C, Ref, {columns, Columns}}
|
|
|
- {C, Ref, no_data} if statement will not return rows
|
|
|
- {C, Ref, {error, Reason}}
|
|
|
+ {C, Ref, {types, Types}}
|
|
|
+ {C, Ref, {columns, Columns}}
|
|
|
+ {C, Ref, no_data} if statement will not return rows
|
|
|
+ {C, Ref, {error, Reason}}
|
|
|
|
|
|
- ok = pgsql:bind(C, Statement, [PortalName], ParameterValues).
|
|
|
+ ok = pgsql:bind(C, Statement, [PortalName], ParameterValues).
|
|
|
|
|
|
PortalName - optional name for the result portal.
|
|
|
|
|
|
both apgsql:bind and ipgsql:bind send {C, Ref, ok | {error, Reason}}
|
|
|
|
|
|
- {ok | partial, Rows} = pgsql:execute(C, Statement, [PortalName], [MaxRows]).
|
|
|
- {ok, Count} = pgsql:execute(C, Statement, [PortalName]).
|
|
|
- {ok, Count, Rows} = pgsql:execute(C, Statement, [PortalName]).
|
|
|
+ {ok | partial, Rows} = pgsql:execute(C, Statement, [PortalName], [MaxRows]).
|
|
|
+ {ok, Count} = pgsql:execute(C, Statement, [PortalName]).
|
|
|
+ {ok, Count, Rows} = pgsql:execute(C, Statement, [PortalName]).
|
|
|
|
|
|
PortalName - optional portal name used in bind/4.
|
|
|
MaxRows - maximum number of rows to return (0 for all rows).
|
|
@@ -206,15 +206,15 @@ provide a common fork for community development.
|
|
|
|
|
|
ipgsql:execute sends
|
|
|
|
|
|
- {C, Ref, {data, Row}}
|
|
|
- {C, Ref, {error, Reason}}
|
|
|
- {C, Ref, suspended} partial result was sent, more rows are available
|
|
|
- {C, Ref, {complete, {_Type, Count}}}
|
|
|
- {C, Ref, {complete, _Type}}
|
|
|
+ {C, Ref, {data, Row}}
|
|
|
+ {C, Ref, {error, Reason}}
|
|
|
+ {C, Ref, suspended} partial result was sent, more rows are available
|
|
|
+ {C, Ref, {complete, {_Type, Count}}}
|
|
|
+ {C, Ref, {complete, _Type}}
|
|
|
|
|
|
- ok = pgsql:close(C, Statement).
|
|
|
- ok = pgsql:close(C, statement | portal, Name).
|
|
|
- ok = pgsql:sync(C).
|
|
|
+ ok = pgsql:close(C, Statement).
|
|
|
+ ok = pgsql:close(C, statement | portal, Name).
|
|
|
+ ok = pgsql:sync(C).
|
|
|
|
|
|
All pgsql functions return {error, Error} when an error occurs.
|
|
|
|
|
@@ -226,49 +226,49 @@ provide a common fork for community development.
|
|
|
Batch execution is bind + execute for several prepared statements.
|
|
|
It uses unnamed portals and MaxRows = 0.
|
|
|
|
|
|
- Results = pgsql:execute_batch(C, Batch).
|
|
|
+ Results = pgsql:execute_batch(C, Batch).
|
|
|
|
|
|
Batch - list of {Statement, ParameterValues}
|
|
|
Results - list of {ok, Count} or {ok, Count, Rows}
|
|
|
|
|
|
Example
|
|
|
|
|
|
- {ok, S1} = pgsql:parse(C, "one", "select $1", [int4]),
|
|
|
- {ok, S2} = pgsql:parse(C, "two", "select $1 + $2", [int4, int4]),
|
|
|
- [{ok, [{1}]}, {ok, [{3}]}] =
|
|
|
- pgsql:execute_batch(C, [{S1, [1]}, {S2, [1, 2]}]).
|
|
|
+ {ok, S1} = pgsql:parse(C, "one", "select $1", [int4]),
|
|
|
+ {ok, S2} = pgsql:parse(C, "two", "select $1 + $2", [int4, int4]),
|
|
|
+ [{ok, [{1}]}, {ok, [{3}]}] =
|
|
|
+ pgsql:execute_batch(C, [{S1, [1]}, {S2, [1, 2]}]).
|
|
|
|
|
|
apgsql:execute_batch sends {C, Ref, Results}
|
|
|
ipgsql:execute_batch sends
|
|
|
|
|
|
- {C, Ref, {data, Row}}
|
|
|
- {C, Ref, {error, Reason}}
|
|
|
- {C, Ref, {complete, {_Type, Count}}}
|
|
|
- {C, Ref, {complete, _Type}}
|
|
|
- {C, Ref, done} - execution of all queries from Batch has finished
|
|
|
+ {C, Ref, {data, Row}}
|
|
|
+ {C, Ref, {error, Reason}}
|
|
|
+ {C, Ref, {complete, {_Type, Count}}}
|
|
|
+ {C, Ref, {complete, _Type}}
|
|
|
+ {C, Ref, done} - execution of all queries from Batch has finished
|
|
|
|
|
|
|
|
|
* Data Representation
|
|
|
|
|
|
- null = null
|
|
|
- bool = true | false
|
|
|
- char = $A | binary
|
|
|
- intX = 1
|
|
|
- floatX = 1.0
|
|
|
- date = {Year, Month, Day}
|
|
|
- time = {Hour, Minute, Second.Microsecond}
|
|
|
- timetz = {time, Timezone}
|
|
|
- timestamp = {date, time}
|
|
|
- timestamptz = {date, time}
|
|
|
- interval = {time, Days, Months}
|
|
|
- text = <<"a">>
|
|
|
- varchar = <<"a">>
|
|
|
- bytea = <<1, 2>>
|
|
|
- array = [1, 2, 3]
|
|
|
-
|
|
|
- record = {int2, time, text, ...} (decode only)
|
|
|
-
|
|
|
- timestamp and timestamptz parameters can take erlang:now() format {MegaSeconds, Seconds, MicroSeconds}
|
|
|
+ null = null
|
|
|
+ bool = true | false
|
|
|
+ char = $A | binary
|
|
|
+ intX = 1
|
|
|
+ floatX = 1.0
|
|
|
+ date = {Year, Month, Day}
|
|
|
+ time = {Hour, Minute, Second.Microsecond}
|
|
|
+ timetz = {time, Timezone}
|
|
|
+ timestamp = {date, time}
|
|
|
+ timestamptz = {date, time}
|
|
|
+ interval = {time, Days, Months}
|
|
|
+ text = <<"a">>
|
|
|
+ varchar = <<"a">>
|
|
|
+ bytea = <<1, 2>>
|
|
|
+ array = [1, 2, 3]
|
|
|
+
|
|
|
+ record = {int2, time, text, ...} (decode only)
|
|
|
+
|
|
|
+ timestamp and timestamptz parameters can take erlang:now() format {MegaSeconds, Seconds, MicroSeconds}
|
|
|
|
|
|
* Errors
|
|
|
|
|
@@ -292,7 +292,7 @@ provide a common fork for community development.
|
|
|
|
|
|
Message formats:
|
|
|
|
|
|
- {pgsql, Connection, {notification, Channel, Pid, Payload}}
|
|
|
+ {pgsql, Connection, {notification, Channel, Pid, Payload}}
|
|
|
|
|
|
Connection - connection the notification occurred on
|
|
|
|
|
@@ -300,7 +300,7 @@ provide a common fork for community development.
|
|
|
Pid - database session pid that sent notification
|
|
|
Payload - optional payload, only available from PostgreSQL >= 9.0
|
|
|
|
|
|
- {pgsql, Connection, {notice, Error}}
|
|
|
+ {pgsql, Connection, {notice, Error}}
|
|
|
|
|
|
Connection - connection the notice occurred on
|
|
|
Error - an #error{} record, see pgsql.hrl
|