posterize v0.12.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);
  • pool - the pool module to use, must match that set on start_link/1 (default: 'Elixir.DBConnection.Sojourn');
  • 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

see query/3,4

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)
  • pool - the pool module to use, must match that set on start_link/1 (default: 'Elixir.DBConnection.Sojourn');
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

see query/3,4

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, String.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);
  • pool - the pool module to use, must match that set on start_link/1 (default: 'Elixir.DBConnection.Sojourn');
  • null - the atom to use as a stand in for postgres’ NULL in encoding and decoding (default: null);
  • mode - set to savepoint to use a savepoint to rollback to before the query on error, otherwise set to transaction (default: transaction);
  • copy_data - whether to add copy data as a final parameter for use with COPY .. FROM STDIN queries, if the query is not copying to the database the data is sent but silently discarded (default: false);

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", []).

posterize:query(Conn, "COPY ints FROM STDIN", ["1\n2\n3\n"], [copy_data: true])
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 - connect 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;
  • sync_connect - block in start_link/1 until connection is set up (default: false)
  • extensions - a list of {Module, Opts} pairs where Module is an implemention of the Postgrex.Extension behaviour and Opts are the extension options;
  • decode_binary - either copy to copy binary values when decoding with default extensions that return binaries or reference to use a reference counted binary of the binary received from the socket. referencing a potentially larger binary can be more efficient if the binary value is going to be garbage collected soon because a copy is avoided. however the larger binary can not be garbage collected until all the refences are garbage collected (defaults to copy);
  • prepare - how to prepare queries, either named to use named queries or unnamed to force unnamed queries (default: named);
  • transactions - set to strict to error on unexpected transaction state, otherwise set to naive (default: naive);
  • pool - the pool module to use, see DBConnection for pool dependent options, this option must be included with all requests contacting the pool if not DBConnection.Connection (default: 'Elixir.DBConnection.Sojourn');
  • null - the atom to use as a stand in for postgres’ NULL in encoding and decoding (default: null);

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

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);
  • pool - the pool module to use, must match that set on start_link/1 (default: 'Elixir.DBConnection.Sojourn');
  • 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).