Postgrex.Connection
Main API for Postgrex. This module handles the connection to postgres.
Summary
| begin!(pid, opts \\ []) | Starts a transaction. Returns |
| begin(pid, opts \\ []) | Starts a transaction. Returns |
| commit!(pid, opts \\ []) | Commits a transaction. Returns |
| commit(pid, opts \\ []) | Commits a transaction. Returns |
| in_transaction(pid, opts \\ [], fun) | Helper for creating reliable transactions. If an error is raised in the given
function the transaction is rolled back, otherwise it is commited. A
transaction can be cancelled with |
| parameters(pid, opts \\ []) | Returns a cached map of connection parameters |
| query!(pid, statement, params, opts \\ []) | Runs an (extended) query and returns the result or raises |
| query(pid, statement, params, opts \\ []) | Runs an (extended) query and returns the result as |
| rollback!(pid, opts \\ []) | Rolls back a transaction. Returns |
| rollback(pid, opts \\ []) | Rolls back a transaction. Returns |
| start_link(opts) | Start the connection process and connect to postgres |
| stop(pid, opts \\ []) | Stop the process and disconnect |
Functions
Specs:
- begin(pid, Keyword.t) :: :ok | {:error, Postgrex.Error.t}
Starts a transaction. Returns :ok or {:error, %Postgrex.Error{}} if an
error occurred. Transactions can be nested with the help of savepoints. A
transaction won’t end until a rollback/1 or commit/1 have been issued for
every begin/1.
Options
:timeout- Call timeout (default:infinity)
Examples
# Transaction begun
Postgrex.Connection.begin(pid)
Postgrex.Connection.query(pid, "INSERT INTO comments (text) VALUES ('first')")
# Nested subtransaction begun
Postgrex.Connection.begin(pid)
Postgrex.Connection.query(pid, "INSERT INTO comments (text) VALUES ('second')")
# Subtransaction rolled back
Postgrex.Connection.rollback(pid)
# Only the first comment will be commited because the second was rolled back
Postgrex.Connection.commit(pid)Specs:
- begin!(pid, Keyword.t) :: :ok
Starts a transaction. Returns :ok if it was successful or raises
Postgrex.Error if an error occurred. See begin/1.
Specs:
- commit(pid, Keyword.t) :: :ok | {:error, Postgrex.Error.t}
Commits a transaction. Returns :ok or {:error, %Postgrex.Error{}} if an
error occurred. See begin/1 for more information.
Options
:timeout- Call timeout (default:infinity)
Specs:
- commit!(pid, Keyword.t) :: :ok
Commits a transaction. Returns :ok if it was successful or raises
Postgrex.Error if an error occurred. See commit/1.
Specs:
- in_transaction(pid, Keyword.t, (() -> term)) :: term
Helper for creating reliable transactions. If an error is raised in the given
function the transaction is rolled back, otherwise it is commited. A
transaction can be cancelled with throw :postgrex_rollback. If there is a
connection error Postgrex.Error will be raised. Do not use this function in
conjunction with begin/1, commit/1 and rollback/1.
Options
:timeout- Call timeout (default:infinity). Note that it is not the maximum timeout of the entire call but rather the timeout of thecommit/2androllback/2calls that this function makes.
Specs:
- parameters(pid, Keyword.t) :: %{}
Returns a cached map of connection parameters.
Options
:timeout- Call timeout (default:infinity)
Specs:
- query(pid, iodata, list, Keyword.t) :: {:ok, Postgrex.Result.t} | {:error, Postgrex.Error.t}
Runs an (extended) query and returns the result as {:ok, %Postgrex.Result{}}
or {:error, %Postgrex.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 elixir values. See the README for information on how Postgrex
encodes and decodes elixir values by default. See Postgrex.Result for the
result data.
A type hinted query is run if both the options :param_types and
:result_types are given. One client-server round trip can be saved by
providing the types to Postgrex because the server doesn’t have to be queried
for the types of the parameters and the result.
Options
:timeout- Call timeout (default:infinity):param_types- A list of type names for the parameters:result_types- A list of type names for the result rows
Examples
Postgrex.Connection.query(pid, "CREATE TABLES posts (id serial, title text)")
Postgrex.Connection.query(pid, "INSERT INTO posts (title) VALUES ('my title')")
Postgrex.Connection.query(pid, "SELECT title FROM posts")
Postgrex.Connection.query(pid, "SELECT $1 + $2", [40, 2]")
Postgrex.Connection.query(pid, "SELECT $1 || $2", ['4', '2'],
param_types: ["text", "text"], result_types: ["text"])Specs:
- query!(pid, iodata, list, Keyword.t) :: Postgrex.Result.t
Runs an (extended) query and returns the result or raises Postgrex.Error if
there was an error. See query/3.
Specs:
- rollback(pid, Keyword.t) :: :ok | {:error, Postgrex.Error.t}
Rolls back a transaction. Returns :ok or {:error, %Postgrex.Error{}} if
an error occurred. See begin/1 for more information.
Options
:timeout- Call timeout (default:infinity)
Specs:
- rollback!(pid, Keyword.t) :: :ok
Rolls back a transaction. Returns :ok if it was successful or raises
Postgrex.Error if an error occurred. See rollback/1.
Specs:
- 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: 5432);:database- Database (required);:username- Username (default: PGUSER env variable, then USER env var);:password- User password (default PGPASSWORD);:encoder- Custom encoder function;:decoder- Custom decoder function;:formatter- Function deciding the format for a type;:parameters- Keyword list of connection parameters;:connect_timeout- Connect timeout in milliseconds (default: 5000);:ssl- Set totrueif ssl should be used (default:false);:ssl_opts- A list of ssl options, see ssl docs;
Function signatures
@spec encoder(info :: TypeInfo.t, default :: fun, param :: term) ::
binary
@spec decoder(info :: TypeInfo.t, default :: fun, bin :: binary) ::
term
@spec formatter(info :: TypeInfo.t) ::
:binary | :text | nil