posterize v0.13.1 posterize
an erlang API for postgrex, a postgres client
Summary
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
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, 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 tosavepoint
to use a savepoint to rollback to before the query on error, otherwise set totransaction
(default:transaction
);
examples
{ok, Query} = posterize:prepare(Conn, "", "CREATE TABLE posts (id serial, title text)"),
ok = posterize:close(Conn, Query).
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 tosavepoint
to use a savepoint to rollback to before the query on error, otherwise set totransaction
(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%">>]).
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 tosavepoint
to use a savepoint to rollback to before the query on error, otherwise set totransaction
(default:transaction
);
examples
{ok, Query} = posterize:prepare(Conn, "name", "CREATE TABLE posts (id serial, title text)").
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 tosavepoint
to use a savepoint to rollback to before the query on error, otherwise set totransaction
(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 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 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 totrue
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, eithernamed
to use named queries orunnamed
to force unnamed queries. useunnamed
when using a proxy like pgbouncer that doesn’t support named queries (default:named
);transactions
- set tostrict
to error on unexpected transaction state, otherwise set tonaive
(default:naive
);Postgrex
(and posterize) use theDBConnection
framework and support allDBConnection
options. seeDBConnection
for more information
examples
1> {ok, Pid} = posterize:start_link([{database, <<”postgres”>>}]) {ok, <0.62.0>}
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 tosavepoint
to use a savepoint to rollback to before the query on error, otherwise set totransaction
(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).