Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Explain unnamed prepared statements in docs #639

Merged
merged 3 commits into from
Jan 25, 2023
Merged

Explain unnamed prepared statements in docs #639

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
203227c
highlight unnamed prepared statements in docs
Jan 25, 2023
089e1a7
typo
Jan 25, 2023
e399387
add connection option
Jan 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 15 additions & 4 deletions lib/postgrex.ex
View file
Open in desktop
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