Postgrex.Connection

Main API for Postgrex. This module handles the connection to postgres.

Summary

Functions

Listens to an asynchronous notification channel using the LISTEN command. A message {:notification, connection_pid, ref, channel, payload} will be sent to the calling process when a notification is received

Listens to an asynchronous notification channel channel. See listen/2

Returns a cached map of connection parameters

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

Runs an (extended) query and returns the result or raises Postgrex.Error if there was an error. See query/3

Start the connection process and connect to postgres

Stop the process and disconnect

Stops listening on the given channel by passing the reference returned from listen/2

Stops listening on the given channel by passing the reference returned from listen/2

Functions

listen(pid, channel, opts \\ [])

Specs

listen(pid, String.t, Keyword.t) :: {:ok, reference}

Listens to an asynchronous notification channel using the LISTEN command. A message {:notification, connection_pid, ref, channel, payload} will be sent to the calling process when a notification is received.

Options

  • :timeout - Call timeout (default: 5000)
listen!(pid, channel, opts \\ [])

Specs

listen!(pid, String.t, Keyword.t) :: reference

Listens to an asynchronous notification channel channel. See listen/2.

parameters(pid, opts \\ [])

Specs

parameters(pid, Keyword.t) :: map

Returns a cached map of connection parameters.

Options

  • :timeout - Call timeout (default: 5000)
query(pid, statement, params, opts \\ [])

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.

Options

  • :timeout - Call timeout (default: 5000)
  • :decode - Decode method: :auto decodes the result and :manual does not (default: :auto)

Examples

Postgrex.Connection.query(pid, "CREATE TABLE 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 id FROM posts WHERE title like $1", ["%my%"])
query!(pid, statement, params, opts \\ [])

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.

start_link(opts)

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);
  • :parameters - Keyword list of connection parameters;
  • :timeout - Connect timeout in milliseconds (default: 5000);
  • :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 implementing the Postgrex.Extension behaviour and opts are the extension options;
stop(pid, opts \\ [])

Specs

stop(pid, Keyword.t) :: :ok

Stop the process and disconnect.

Options

  • :timeout - Call timeout (default: 5000)
unlisten(pid, ref, opts \\ [])

Specs

unlisten(pid, reference, Keyword.t) :: :ok

Stops listening on the given channel by passing the reference returned from listen/2.

Options

  • :timeout - Call timeout (default: 5000)
unlisten!(pid, ref, opts \\ [])

Specs

unlisten!(pid, reference, Keyword.t) :: :ok

Stops listening on the given channel by passing the reference returned from listen/2.