Ecto v2.0.5 Ecto.Adapters.SQL

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.Query about building queries.

Summary

Functions

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

to_sql(kind, repo, queryable)

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

Functions

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

Specs

query(Ecto.Repo.t, String.t, [term], Keyword.t) ::
  {:ok, %{rows: nil | [tuple], num_rows: non_neg_integer}} |
  {: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}}

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

Specs

query!(Ecto.Repo.t, String.t, [term], Keyword.t) ::
  %{rows: nil | [tuple], num_rows: non_neg_integer} |
  no_return

Same as query/4 but raises on invalid queries.

to_sql(kind, repo, queryable)

Specs

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:

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

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