posterize v0.2.0 :posterize
an erlang API for postgrex
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. See
Postgrex.Query
for the query data
runs an (extended) prepared query and returns the result as
{ok, Result}
or {error, Error}
if there was an
error. parameters are given as part of the prepared query, %Postgrex.Query{}
.
See the README for information on how Postgrex encodes and decodes Elixir
values by default. See Postgrex.Query
for the query data and
Postgrex.Result
for the result data
returns a cached map of connection parameters
runs an (extended) query and returns the result as {ok, Result}
or {error, Error}
if there was an 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 postergirl
encodes and decodes erlang values by default
rollback a transaction, does not return
aborts the current transaction fun. if inside multiple transaction/3
functions, bubbles up to the top level
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 :: DBConnection.conn
a connection process name, pid or reference.
a connection reference is used when making multiple requests to the same
connection, see transaction/3
and after_connect
in start_link/1
.
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. See
Postgrex.Query
for the query data.
options
options are a proplist where the following keys are valid
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
- Close request timeout (default:5000
);pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
examples
{ok, Query} = posterize:prepare(Conn, <<"CREATE TABLE posts (id serial, title text)">>),
ok = posterize:close(Conn, Query).
Specs
runs an (extended) prepared query and returns the result as
{ok, Result}
or {error, Error}
if there was an
error. parameters are given as part of the prepared query, %Postgrex.Query{}
.
See the README for information on how Postgrex encodes and decodes Elixir
values by default. See Postgrex.Query
for the query data and
Postgrex.Result
for the result data.
options
options are a proplist where the following keys are valid
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
- Execute request timeout (default:5000
);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 onstart_link/1
, seeDBConnection
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%">>]).
Specs
parameters(pid, Keyword.t) :: map
returns a cached map of connection parameters.
options
options are a proplist where the following keys are valid
timeout
- Call timeout (default:5000
)
Specs
prepares an (extended) query and returns the result as
{ok, Result}
or {error, Error}
if there was an
error. parameters can be set in the query as $1
embedded in the query
string. to execute the query call execute/4
. to close the prepared query
call close/3
options
options are a proplist where the following keys are valid
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
- Prepare request timeout (default:5000
);pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
examples
{ok, Query} = posterize:prepare(Conn, <<"CREATE TABLE posts (id serial, title text)">>).
runs an (extended) query and returns the result as {ok, Result}
or {error, Error}
if there was an 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 postergirl
encodes and decodes erlang values by default
options
options are a proplist where the following keys are valid
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:5000
);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 onstart_link/1
, seeDBConnection
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%">>]).
Specs
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!", [])
end).
Specs
start_link(Keyword.t) ::
{:ok, pid} |
{:error, Postgrex.Error.t | term}
start the connection process and connect to postgres
options
options are a proplist where the following keys are valid
hostname
- server hostname (default: PGHOST env variable, then localhost);port
- server port (default: 5432);database
- database (required);username
- username (default: PGUSER env variable, then USER env var);password
- user password (default PGPASSWORD);parameters
- proplist of connection parameters;timeout
- connect timeout in milliseconds (default:5000
);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;sync_connect
- block instart_link/1
until connection is set up (default:false
)extensions
- a list of{Module, Opts}
pairs whereModule
is implementing thePostgrex.Extension
behaviour andOpts
are the extension options;after_connect
- a function to run on connect, either a 1-arity fun called with a connection reference,{Module, Function, Args}
with the connection reference prepended toArgs
ornil
, (default:nil
)idle_timeout
- idle timeout to ping postgres to maintain a connection (default:5000
)backoff_start
- the first backoff interval when reconnecting (default:200
);backoff_max
- the maximum backoff interval when reconnecting (default:15_000
);backoff_type
- the backoff strategy when reconnecting,stop
for no backoff and to stop (seebackoff
, default:jitter
)transactions
- set tostrict
to error on unexpected transaction state, otherwise set tonaive
(default:naive
);pool
- the pool module to use, seeDBConnection
, it must be included with all requests if not the default (default:DBConnection.Connection
);
Specs
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
options are a proplist where the following keys are valid
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:5000
);pool
- The pool module to use, must match that set onstart_link/1
, seeDBConnection
mode
- Set tosavepoint
to use savepoints instead of an SQL transaction, 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).