posterize v0.13.1 posterize

an erlang API for postgrex, a postgres client

Summary

Types

a connection process name, pid or reference

Functions

closes an (extended) prepared query and returns ok or {error, Error} if there was an error. closing a query releases any resources held by postgresql for a prepared query with that name

runs an (extended) prepared query and returns the result as {ok, Result} or {error, Error} if there was an error

returns a cached map of connection parameters

prepares an (extended) query and returns a prepared query as {ok, Query} or {error, Error} if there was an error. execute the returned query with execute/3,4

runs an (extended) query and returns the result as {ok, Result} or {error, Error} if there was a database error. parameters can be set in the query as $1 embedded in the query string. parameters are given as a list of erlang values. see the README for information on how posterize encodes and decodes erlang values by default. see Postgrex.Result for the result data

rollback a transaction, does not return

start the connection process and connect to postgres

acquire a lock on a connection and run a series of requests inside a transaction. the result of the transaction fun is return inside an ok tuple: {ok, Result}

Types

conn()

a connection process name, pid or reference

a connection reference is used when making multiple requests to the same connection, see transaction/3

Functions

close(conn, query)
close(conn, query, opts)
close(conn, Postgrex.Query.t, Keyword.t) ::
  :ok |
  {:error, Postgrex.Error.t}

closes an (extended) prepared query and returns ok or {error, Error} if there was an error. closing a query releases any resources held by postgresql for a prepared query with that name

options

  • pool_timeout - time to wait in the queue for the connection (default: 5000)
  • queue - whether to wait for connection in a queue (default: true);
  • timeout - query request timeout (default: 15000);
  • mode - set to savepoint to use a savepoint to rollback to before the query on error, otherwise set to transaction (default: transaction);

examples

{ok, Query} = posterize:prepare(Conn, "", "CREATE TABLE posts (id serial, title text)"),
ok = posterize:close(Conn, Query).
execute(conn, query, params)
execute(conn, query, params, opts)
execute(conn, Postgrex.Query.t, list, Keyword.t) ::
  {:ok, Postgrex.Result.t} |
  {:error, Postgrex.Error.t}

runs an (extended) prepared query and returns the result as {ok, Result} or {error, Error} if there was an error

options

  • pool_timeout - time to wait in the queue for the connection (default: 5000)
  • queue - whether to wait for connection in a queue (default: true);
  • timeout - query request timeout (default: 15000);
  • decode_mapper - fun to map each row in the result to a term after decoding, (default: fun(X) -> X end);
  • mode - set to savepoint to use a savepoint to rollback to before the query on error, otherwise set to transaction (default: transaction);

examples

{ok, Query} = posterize:prepare(Conn, "", "CREATE TABLE posts (id serial, title text)"),
{ok, Result} = posterize:execute(Conn, Query, []).

{ok, Query} = posterize:prepare(Conn, "", "SELECT id FROM posts WHERE title like $1"),
{ok, Result} = posterize:execute(Conn, Query, [<<"%my%">>]).
parameters(pid, opts \\ [])
parameters(pid, Keyword.t) :: map

returns a cached map of connection parameters.

options

  • timeout - Call timeout (default: 15000)
prepare(conn, name, statement)
prepare(conn, name, statement, opts)
prepare(conn, iodata, iodata, Keyword.t) ::
  {:ok, Postgrex.Query.t} |
  {:error, Postgrex.Error.t}

prepares an (extended) query and returns a prepared query as {ok, Query} or {error, Error} if there was an error. execute the returned query with execute/3,4

options

  • pool_timeout - time to wait in the queue for the connection (default: 5000)
  • queue - whether to wait for connection in a queue (default: true);
  • timeout - query request timeout (default: 15000);
  • mode - set to savepoint to use a savepoint to rollback to before the query on error, otherwise set to transaction (default: transaction);

examples

{ok, Query} = posterize:prepare(Conn, "name", "CREATE TABLE posts (id serial, title text)").
query(conn, statement, params)
query(conn, statement, params, opts)
query(conn, iodata, list, Keyword.t) ::
  {:ok, Postgrex.Result.t} |
  {:error, Postgrex.Error.t}

runs an (extended) query and returns the result as {ok, Result} or {error, Error} if there was a database error. parameters can be set in the query as $1 embedded in the query string. parameters are given as a list of erlang values. see the README for information on how posterize encodes and decodes erlang values by default. see Postgrex.Result for the result data

options

  • pool_timeout - time to wait in the queue for the connection (default: 5000)
  • queue - whether to wait for connection in a queue (default: true);
  • timeout - query request timeout (default: 15000);
  • decode_mapper - fun to map each row in the result to a term after decoding, (default: fun(X) -> X end);
  • mode - set to savepoint to use a savepoint to rollback to before the query on error, otherwise set to transaction (default: transaction);

examples

posterize:query(Conn, "CREATE TABLE posts (id serial, title text)", []).

posterize:query(Conn, "INSERT INTO posts (title) VALUES ('my title')", []).

posterize:query(Conn, "SELECT title FROM posts", []).

posterize:query(Conn, "SELECT id FROM posts WHERE title like $1", [<<"%my%">>]).

posterize:query(Conn, "COPY posts TO STDOUT", []).
rollback(conn, any)
rollback(DBConnection.t, any) :: no_return

rollback a transaction, does not return

aborts the current transaction fun. if inside multiple transaction/3 functions, bubbles up to the top level

example

{error, oops} = posterize:transaction(Conn, fun(Conn) ->
  posterize:rollback(Conn, bar),
  io:format("never reaches here!~n", [])
end).
start_link(opts)
start_link(Keyword.t) ::
  {:ok, pid} |
  {:error, Postgrex.Error.t | term}

start the connection process and connect to postgres

options

  • hostname - server hostname (default: PGHOST env variable, then localhost);
  • port - server port (default: PGPORT env variable, then 5432);
  • database - database (required);
  • username - username (default: PGUSER env variable, then USER env var);
  • password - user password (default PGPASSWORD env variable);
  • parameters - proplist of connection parameters;
  • timeout - socket receive timeout when idle in milliseconds (default: 15000);
  • connect_timeout - socket connect timeout in milliseconds (default: 15000);
  • handshake_timeout - connection handshake timeout in milliseconds (default: 15000);
  • ssl - set to true if ssl should be used (default: false);
  • ssl_opts - a list of ssl options, see ssl docs;
  • socket_options - options to be given to the underlying socket;
  • prepare - how to prepare queries, either named to use named queries or unnamed to force unnamed queries. use unnamed when using a proxy like pgbouncer that doesn’t support named queries (default: named);
  • transactions - set to strict to error on unexpected transaction state, otherwise set to naive (default: naive);

    Postgrex (and posterize) use the DBConnection framework and support all DBConnection options. see DBConnection for more information

examples

1> {ok, Pid} = posterize:start_link([{database, <<”postgres”>>}]) {ok, <0.62.0>}

transaction(conn, fun)
transaction(conn, fun, opts)
transaction(conn, (DBConnection.t -> result), Keyword.t) ::
  {:ok, result} |
  {:error, any} when result: var

acquire a lock on a connection and run a series of requests inside a transaction. the result of the transaction fun is return inside an ok tuple: {ok, Result}

to use the locked connection call the request with the connection reference passed as the single argument to the Fun. if the connection disconnects all future calls using that connection reference will fail

rollback/2 rolls back the transaction and causes the function to return {error, Error}

transaction/3 can be nested multiple times if the connection reference is used to start a nested transaction. the top level transaction function is the actual transaction

options

  • pool_timeout - time to wait in the queue for the connection (default: 5000)
  • queue - whether to wait for connection in a queue (default: true);
  • timeout - transaction timeout (default: 15000);
  • mode - set to savepoint to use a savepoint to rollback to before the query on error, otherwise set to transaction (default: transaction);

the timeout is for the duration of the transaction and all nested transactions and requests. this timeout overrides timeouts set by internal transactions and requests. the pool and mode will be used for all requests inside the transaction function

example

Fun = fun(Conn) -> posterize:query(Conn, "", "SELECT title FROM posts", []) end,
{ok, Result} = posterize:transaction(Conn, Fun).