Skip to content

Commit

Permalink
Explain unnamed prepared statements in docs (#639)
Browse files Browse the repository at this point in the history
  • Loading branch information
greg-rychlewski authored Jan 25, 2023
1 parent 8a9ae87 commit f092eb7
Showing 1 changed file with 15 additions and 4 deletions.
19 changes: 15 additions & 4 deletions lib/postgrex.ex
Original file line number Diff line number Diff line change
Expand Up @@ -377,16 +377,22 @@ defmodule Postgrex do
end

@doc """
Prepares an (extended) query and returns the result as
`{:ok, %Postgrex.Query{}}` or `{:error, %Postgrex.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
Prepares an (extended) query.
It returns the result as `{:ok, %Postgrex.Query{}}` or `{:error, %Postgrex.Error{}}`
if there was an error. Parameters can be set in the query as `$1` embedded in the
query string. To execute execute the query call `execute/4`. To close the prepared query
call `close/3`. See `Postgrex.Query` for the query data.
This function may still raise an exception if there is an issue with types
(`ArgumentError`), connection (`DBConnection.ConnectionError`), ownership
(`DBConnection.OwnershipError`) or other error (`RuntimeError`).
For unnamed prepared statements, pass an empty string for `name`. This can be useful
when trying to avoid the generic query plan Postgres creates for named prepared
statements. You may also set `prepare: :unnamed` at the connection level so that
every prepared statement using that connection will be unnamed.
## Options
* `:queue` - Whether to wait for connection in a queue (default: `true`);
Expand Down Expand Up @@ -423,6 +429,11 @@ defmodule Postgrex do
`{:error, %Postgrex.Error{}}` if there was an error. Parameters are given as
part of the prepared query, `%Postgrex.Query{}`.
For unnamed prepared statements, pass an empty string for `name`. This can be useful
when trying to avoid the generic query plan Postgres creates for named prepared
statements. You may also set `prepare: :unnamed` at the connection level so that
every prepared statement using that connection will be unnamed.
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.
Expand Down

0 comments on commit f092eb7

Please sign in to comment.