|
@@ -16,10 +16,10 @@ provide a common fork for community development.
|
|
|
|
|
|
* Difference highlights
|
|
|
|
|
|
- + 3 API sets: pgsql, apgsql and ipgsql:
|
|
|
- pgsql maintains backwards compatibility with the original driver API,
|
|
|
- apgsql delivers complete results as regular erlang messages,
|
|
|
- ipgsql delivers results as messages incrementally (row by row)
|
|
|
+ + 3 API sets: epgsql, epgsqla and epgsqli:
|
|
|
+ epgsql maintains backwards compatibility with the original driver API,
|
|
|
+ epgsqla delivers complete results as regular erlang messages,
|
|
|
+ epgsqli delivers results as messages incrementally (row by row)
|
|
|
+ internal queue of client requests, so you don't need to wait for the
|
|
|
response to send the next request
|
|
|
+ single process to hold driver state and receive socket data
|
|
@@ -46,7 +46,7 @@ provide a common fork for community development.
|
|
|
|
|
|
* Connect
|
|
|
|
|
|
- {ok, C} = pgsql:connect(Host, [Username], [Password], Opts).
|
|
|
+ {ok, C} = epgsql:connect(Host, [Username], [Password], Opts).
|
|
|
|
|
|
Host - host to connect to.
|
|
|
Username - username to connect as, defaults to $USER.
|
|
@@ -63,16 +63,16 @@ provide a common fork for community development.
|
|
|
|
|
|
Example:
|
|
|
|
|
|
- {ok, C} = pgsql:connect("localhost", "username", [{database, "test_db"}]).
|
|
|
- ok = pgsql:close(C).
|
|
|
+ {ok, C} = epgsql:connect("localhost", "username", [{database, "test_db"}]).
|
|
|
+ ok = epgsql: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):
|
|
|
+ Asynchronous connect example (applies to epgsqli too):
|
|
|
|
|
|
- {ok, C} = apgsql:start_link(),
|
|
|
- Ref = apgsql:connect(C, "localhost", "username", [{database, "test_db"}]),
|
|
|
+ {ok, C} = epgsqla:start_link(),
|
|
|
+ Ref = epgsqla:connect(C, "localhost", "username", [{database, "test_db"}]),
|
|
|
receive
|
|
|
{C, Ref, connected} ->
|
|
|
{ok, C};
|
|
@@ -85,13 +85,13 @@ provide a common fork for community development.
|
|
|
|
|
|
* 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} = epgsql:squery(C, "select ...").
|
|
|
+ {ok, Count} = epgsql:squery(C, "update ...").
|
|
|
+ {ok, Count, Columns, Rows} = epgsql:squery(C, "insert ... returning ...").
|
|
|
|
|
|
- {error, Error} = pgsql:squery(C, "invalid SQL").
|
|
|
+ {error, Error} = epgsql:squery(C, "invalid SQL").
|
|
|
|
|
|
- + `Columns` - list of column records, see pgsql.hrl for definition.
|
|
|
+ + `Columns` - list of column records, see epgsql.hrl for definition.
|
|
|
+ `Rows` - list of tuples, one for each row.
|
|
|
+ `Count` - integer count of rows inserted/updated/etc
|
|
|
|
|
@@ -101,21 +101,21 @@ 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").
|
|
|
+ epgsql:squery(C, "select 1; select 2").
|
|
|
|
|
|
- `apgsql:squery` returns result as a single message:
|
|
|
+ `epgsqla:squery` returns result as a single message:
|
|
|
|
|
|
- Ref = apgsql:squery(C, Sql),
|
|
|
+ Ref = epgsqla:squery(C, Sql),
|
|
|
receive
|
|
|
{C, Ref, Result} -> Result
|
|
|
end.
|
|
|
|
|
|
- `Result` has same format as return value of pgsql:squery.
|
|
|
+ `Result` has same format as return value of epgsql:squery.
|
|
|
|
|
|
- `ipgsql:squery` returns results incrementally for each query inside Sql and
|
|
|
+ `epgsqli:squery` returns results incrementally for each query inside Sql and
|
|
|
for each row:
|
|
|
|
|
|
- Ref = ipgsql:squery(C, Sql),
|
|
|
+ Ref = epgsqli:squery(C, Sql),
|
|
|
receive
|
|
|
{C, Ref, {columns, Columns}} ->
|
|
|
%% columns description
|
|
@@ -139,11 +139,11 @@ provide a common fork for community development.
|
|
|
|
|
|
* 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} = epgsql:equery(C, "select ...", [Parameters]).
|
|
|
+ {ok, Count} = epgsql:equery(C, "update ...", [Parameters]).
|
|
|
+ {ok, Count, Columns, Rows} = epgsql:equery(C, "insert ... returning ...", [Parameters]).
|
|
|
|
|
|
- {error, Error} = pgsql:equery(C, "invalid SQL", [Parameters]).
|
|
|
+ {error, Error} = epgsql:equery(C, "invalid SQL", [Parameters]).
|
|
|
|
|
|
+ `Parameters` - optional list of values to be bound to $1, $2, $3, etc.
|
|
|
|
|
@@ -155,59 +155,59 @@ provide a common fork for community development.
|
|
|
|
|
|
PostgreSQL's binary format is used to return integers as Erlang
|
|
|
integers, floats as floats, bytea/text/varchar columns as binaries,
|
|
|
- bools as true/false, etc. For details see `pgsql_binary.erl` and the
|
|
|
+ bools as true/false, etc. For details see `epgsql_binary.erl` and the
|
|
|
Data Representation section below.
|
|
|
|
|
|
Asynchronous api equery requires you to parse statement beforehand
|
|
|
|
|
|
- Ref = apgsql:equery(C, Statement, [Parameters]),
|
|
|
+ Ref = epgsqla: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`.
|
|
|
+ + `Res` has same format as return value of `epgsql:equery`.
|
|
|
|
|
|
- `ipgsql:equery(C, Statement, [Parameters])` sends same set of messages as
|
|
|
+ `epgsqli:equery(C, Statement, [Parameters])` sends same set of messages as
|
|
|
squery including the final `{C, Ref, done}`.
|
|
|
|
|
|
|
|
|
* Parse/Bind/Execute
|
|
|
|
|
|
- {ok, Statement} = pgsql:parse(C, [StatementName], Sql, [ParameterTypes]).
|
|
|
+ {ok, Statement} = epgsql:parse(C, [StatementName], Sql, [ParameterTypes]).
|
|
|
|
|
|
+ `StatementName` - optional, reusable, name for the prepared statement.
|
|
|
+ `ParameterTypes` - optional list of PostgreSQL types for each parameter.
|
|
|
|
|
|
- For valid type names see `pgsql_types.erl`.
|
|
|
+ For valid type names see `epgsql_types.erl`.
|
|
|
|
|
|
- `apgsql:parse` sends `{C, Ref, {ok, Statement} | {error, Reason}}`.
|
|
|
- `ipgsql:parse` sends:
|
|
|
+ `epgsqla:parse` sends `{C, Ref, {ok, Statement} | {error, Reason}}`.
|
|
|
+ `epgsqli:parse` sends:
|
|
|
|
|
|
{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 = epgsql:bind(C, Statement, [PortalName], ParameterValues).
|
|
|
|
|
|
+ `PortalName` - optional name for the result portal.
|
|
|
|
|
|
- both `apgsql:bind` and `ipgsql:bind` send `{C, Ref, ok | {error, Reason}}`
|
|
|
+ both `epgsqla:bind` and `epgsqli: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} = epgsql:execute(C, Statement, [PortalName], [MaxRows]).
|
|
|
+ {ok, Count} = epgsql:execute(C, Statement, [PortalName]).
|
|
|
+ {ok, Count, Rows} = epgsql:execute(C, Statement, [PortalName]).
|
|
|
|
|
|
+ `PortalName` - optional portal name used in `bind/4`.
|
|
|
+ `MaxRows` - maximum number of rows to return (0 for all rows).
|
|
|
|
|
|
execute returns `{partial, Rows}` when more rows are available.
|
|
|
|
|
|
- `apgsql:execute` sends `{C, Ref, Result}` where `Result` has the same
|
|
|
- format as the return value of `pgsql:execute`.
|
|
|
+ `epgsqla:execute` sends `{C, Ref, Result}` where `Result` has the same
|
|
|
+ format as the return value of `epgsql:execute`.
|
|
|
|
|
|
- `ipgsql:execute` sends
|
|
|
+ `epgsqli:execute` sends
|
|
|
|
|
|
{C, Ref, {data, Row}}
|
|
|
{C, Ref, {error, Reason}}
|
|
@@ -215,13 +215,13 @@ provide a common fork for community development.
|
|
|
{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 = epgsql:close(C, Statement).
|
|
|
+ ok = epgsql:close(C, statement | portal, Name).
|
|
|
+ ok = epgsql:sync(C).
|
|
|
|
|
|
- All pgsql functions return `{error, Error}` when an error occurs.
|
|
|
+ All epgsql functions return `{error, Error}` when an error occurs.
|
|
|
|
|
|
- apgsql and ipgsql close and sync functions send `{C, Ref, ok}`.
|
|
|
+ epgsqla and epgsqli close and sync functions send `{C, Ref, ok}`.
|
|
|
|
|
|
|
|
|
* Batch execution
|
|
@@ -229,20 +229,20 @@ 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 = epgsql: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, S1} = epgsql:parse(C, "one", "select $1", [int4]),
|
|
|
+ {ok, S2} = epgsql:parse(C, "two", "select $1 + $2", [int4, int4]),
|
|
|
[{ok, [{1}]}, {ok, [{3}]}] =
|
|
|
- pgsql:execute_batch(C, [{S1, [1]}, {S2, [1, 2]}]).
|
|
|
+ epgsql:execute_batch(C, [{S1, [1]}, {S2, [1, 2]}]).
|
|
|
|
|
|
- `apgsql:execute_batch` sends `{C, Ref, Results}`
|
|
|
- `ipgsql:execute_batch` sends
|
|
|
+ `epgsqla:execute_batch` sends `{C, Ref, Results}`
|
|
|
+ `epgsqli:execute_batch` sends
|
|
|
|
|
|
{C, Ref, {data, Row}}
|
|
|
{C, Ref, {error, Reason}}
|
|
@@ -276,13 +276,13 @@ provide a common fork for community development.
|
|
|
* Errors
|
|
|
|
|
|
Errors originating from the PostgreSQL backend are returned as `{error, #error{}}`,
|
|
|
- see `pgsql.hrl` for the record definition. epgsql functions may also return
|
|
|
+ see `epgsql.hrl` for the record definition. epgsql functions may also return
|
|
|
`{error, What}` where What is one of the following:
|
|
|
|
|
|
+ `{unsupported_auth_method, Method}` - required auth method is unsupported
|
|
|
+ `timeout` - request timed out
|
|
|
+ `closed` - connection was closed
|
|
|
- + `sync_required` - error occured and pgsql:sync must be called
|
|
|
+ + `sync_required` - error occured and epgsql:sync must be called
|
|
|
|
|
|
* Server Notifications
|
|
|
|
|
@@ -290,22 +290,22 @@ provide a common fork for community development.
|
|
|
to notice and warning messages generated by the server, and "notifications" which
|
|
|
are generated by the LISTEN/NOTIFY mechanism.
|
|
|
|
|
|
- Passing the `{async, Pid}` option to `pgsql:connect` will result in these async
|
|
|
+ Passing the `{async, Pid}` option to `epgsql:connect` will result in these async
|
|
|
messages being sent to the specified process, otherwise they will be dropped.
|
|
|
|
|
|
Message formats:
|
|
|
|
|
|
- `{pgsql, Connection, {notification, Channel, Pid, Payload}}`
|
|
|
+ `{epgsql, Connection, {notification, Channel, Pid, Payload}}`
|
|
|
|
|
|
+ `Connection` - connection the notification occurred on
|
|
|
+ `Channel` - channel the notification occurred on
|
|
|
+ `Pid` - database session pid that sent notification
|
|
|
+` Payload` - optional payload, only available from PostgreSQL >= 9.0
|
|
|
|
|
|
- {pgsql, Connection, {notice, Error}}
|
|
|
+ {epgsql, Connection, {notice, Error}}
|
|
|
|
|
|
+ `Connection` - connection the notice occurred on
|
|
|
- + `Error` - an `#error{}` record, see `pgsql.hrl`
|
|
|
+ + `Error` - an `#error{}` record, see `epgsql.hrl`
|
|
|
|
|
|
|
|
|
* Mailing list / forum
|