posterize v0.12.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
);pool
- the pool module to use, must match that set onstart_link/1
(default:'Elixir.DBConnection.Sojourn'
);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
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%">>]).
returns a cached map of connection parameters.
options
timeout
- Call timeout (default:15000
)pool
- the pool module to use, must match that set onstart_link/1
(default:'Elixir.DBConnection.Sojourn'
);
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, 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 onstart_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 tosavepoint
to use a savepoint to rollback to before the query on error, otherwise set totransaction
(default:transaction
);copy_data
- whether to add copy data as a final parameter for use withCOPY .. 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 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
- connect 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;sync_connect
- block instart_link/1
until connection is set up (default:false
)extensions
- a list of{Module, Opts}
pairs whereModule
is an implemention of thePostgrex.Extension
behaviour andOpts
are the extension options;decode_binary
- eithercopy
to copy binary values when decoding with default extensions that return binaries orreference
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 tocopy
);prepare
- how to prepare queries, eithernamed
to use named queries or unnamed to force unnamed queries (default:named
);transactions
- set tostrict
to error on unexpected transaction state, otherwise set tonaive
(default:naive
);pool
- the pool module to use, seeDBConnection
for pool dependent options, this option must be included with all requests contacting the pool if notDBConnection.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 theDBConnection
framework and support allDBConnection
options. seeDBConnection
for more information
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 onstart_link/1
(default:'Elixir.DBConnection.Sojourn'
);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).