Ecto v2.2.9 Ecto.Adapters.SQL View Source

Behaviour and implementation for SQL adapters.

The implementation for SQL adapter relies on DBConnection to provide pooling, prepare, execute and more.

Developers that use Ecto.Adapters.SQL should implement the callbacks required both by this module and the ones from Ecto.Adapters.SQL.Connection for handling connections and performing queries.

Link to this section Summary

Functions

do_stream(repo, arg2, arg, params, mapper, opts)

query(repo, sql, params \\ [], opts \\ [])

Runs custom SQL query on given repo

query!(repo, sql, params \\ [], opts \\ [])

Same as query/4 but raises on invalid queries

stream(repo, sql, params \\ [], opts \\ [])

Returns a stream that runs a custom SQL query on given repo when reduced

to_sql(kind, repo, queryable)

Converts the given query to SQL according to its kind and the adapter in the given repository

Link to this section Functions

do_stream(repo, arg2, arg, params, mapper, opts)

query(repo, sql, params \\ [], opts \\ [])

query(Ecto.Repo.t(), String.t(), [term()], Keyword.t()) ::
  {:ok,
   %{
     :rows => nil | [[term()] | binary()],
     :num_rows => non_neg_integer(),
     optional(atom()) => any()
   }}
  | {:error, Exception.t()}

Runs custom SQL query on given repo.

In case of success, it must return an :ok tuple containing a map with at least two keys:

:num_rows - the number of rows affected
:rows - the result set as a list. nil may be returned instead of the list if the command does not yield any row as result (but still yields the number of affected rows, like a delete command without returning would)

Options

:timeout - The time in milliseconds to wait for a query to finish, :infinity will wait indefinitely. (default: 15_000)
:pool_timeout - The time in milliseconds to wait for a call to the pool to finish, :infinity will wait indefinitely. (default: 5_000)
:log - When false, does not log the query

Examples

iex> Ecto.Adapters.SQL.query(MyRepo, "SELECT $1::integer + $2", [40, 2])
{:ok, %{rows: [[42]], num_rows: 1}}

For convenience, this function is also available under the repository:

iex> MyRepo.query("SELECT $1::integer + $2", [40, 2])
{:ok, %{rows: [[42]], num_rows: 1}}

query!(repo, sql, params \\ [], opts \\ [])

query!(Ecto.Repo.t(), String.t(), [term()], Keyword.t()) ::
  %{
    :rows => nil | [[term()] | binary()],
    :num_rows => non_neg_integer(),
    optional(atom()) => any()
  }
  | no_return()

Same as query/4 but raises on invalid queries.

stream(repo, sql, params \\ [], opts \\ [])

stream(Ecto.Repo.t(), String.t(), [term()], Keyword.t()) :: Enum.t()

Returns a stream that runs a custom SQL query on given repo when reduced.

In case of success it is a enumerable containing maps with at least two keys:

:num_rows - the number of rows affected
:rows - the result set as a list. nil may be returned instead of the list if the command does not yield any row as result (but still yields the number of affected rows, like a delete command without returning would)

In case of failure it raises an exception.

If the adapter supports a collectable stream, the stream may also be used as the collectable in Enum.into/3. Behaviour depends on the adapter.

Options

:timeout - The time in milliseconds to wait for a query to finish, :infinity will wait indefinitely (default: 15_000)
:pool_timeout - The time in milliseconds to wait for a call to the pool to finish, :infinity will wait indefinitely (default: 5_000)
:log - When false, does not log the query
:max_rows - The number of rows to load from the database as we stream

Examples

iex> Ecto.Adapters.SQL.stream(MyRepo, "SELECT $1::integer + $2", [40, 2]) |> Enum.to_list()
[%{rows: [[42]], num_rows: 1}]

to_sql(kind, repo, queryable)

to_sql(:all | :update_all | :delete_all, Ecto.Repo.t(), Ecto.Queryable.t()) ::
  {String.t(), [term()]}

Converts the given query to SQL according to its kind and the adapter in the given repository.

Examples

The examples below are meant for reference. Each adapter will return a different result:

iex> Ecto.Adapters.SQL.to_sql(:all, repo, Post)
{"SELECT p.id, p.title, p.inserted_at, p.created_at FROM posts as p", []}

iex> Ecto.Adapters.SQL.to_sql(:update_all, repo,
                              from(p in Post, update: [set: [title: ^"hello"]]))
{"UPDATE posts AS p SET title = $1", ["hello"]}

This function is also available under the repository with name to_sql:

iex> Repo.to_sql(:all, Post)
{"SELECT p.id, p.title, p.inserted_at, p.created_at FROM posts as p", []}