# `Ecto.Adapters.SQL.Connection`
[🔗](https://github.com/elixir-ecto/ecto_sql/blob/v3.14.0/lib/ecto/adapters/sql/connection.ex#L1)

Specifies the behaviour to be implemented by all SQL connections.

# `cached`

```elixir
@type cached() :: map()
```

The cached query which is a DBConnection Query

# `connection`

```elixir
@type connection() :: DBConnection.conn()
```

# `name`

```elixir
@type name() :: String.t()
```

The query name

# `params`

```elixir
@type params() :: [term()]
```

# `statement`

```elixir
@type statement() :: String.t()
```

The SQL statement

# `all`

```elixir
@callback all(query :: Ecto.Query.t()) :: iodata()
```

Receives a query and must return a SELECT query.

# `child_spec`

```elixir
@callback child_spec(options :: Keyword.t()) ::
  :supervisor.child_spec() | {module(), Keyword.t()}
```

Receives options and returns `DBConnection` supervisor child
specification.

# `ddl_logs`

```elixir
@callback ddl_logs(result :: term()) :: [
  {Logger.level(), Logger.message(), Logger.metadata()}
]
```

Receives a query result and returns a list of logs.

# `delete`

```elixir
@callback delete(
  prefix :: String.t(),
  table :: String.t(),
  filters :: [atom()],
  returning :: [atom()]
) :: iodata()
```

Returns a DELETE for the `filters` returning the given `returning`.

# `delete_all`

```elixir
@callback delete_all(query :: Ecto.Query.t()) :: iodata()
```

Receives a query and must return a DELETE query.

# `execute`

```elixir
@callback execute(connection(), cached(), params(), options :: Keyword.t()) ::
  {:ok, cached(), term()} | {:ok, term()} | {:error | :reset, Exception.t()}
```

Executes a cached query.

# `execute_ddl`

```elixir
@callback execute_ddl(command :: Ecto.Adapter.Migration.command()) ::
  String.t() | [iodata()]
```

Receives a DDL command and returns a query that executes it.

# `explain_query`

```elixir
@callback explain_query(
  connection(),
  query :: String.t(),
  params :: Keyword.t(),
  opts :: Keyword.t()
) :: {:ok, term()} | {:error, Exception.t()}
```

Executes an EXPLAIN query or similar depending on the adapter to obtains statistics of the given query.

Receives the `connection`, `query`, `params` for the query,
and all `opts` including those related to the EXPLAIN statement and shared opts.

Must execute the explain query and return the result.

# `insert`

```elixir
@callback insert(
  prefix :: String.t(),
  table :: String.t(),
  header :: [atom()],
  rows :: [[atom() | nil]],
  on_conflict :: Ecto.Adapter.Schema.on_conflict(),
  returning :: [atom()],
  placeholders :: [term()],
  opts :: Keyword.t()
) :: iodata()
```

Returns an INSERT for the given `rows` in `table` returning
the given `returning`.

# `prepare_execute`

```elixir
@callback prepare_execute(
  connection(),
  name(),
  statement(),
  params(),
  options :: Keyword.t()
) ::
  {:ok, cached(), term()} | {:error, Exception.t()}
```

Prepares and executes the given query with `DBConnection`.

# `query`

```elixir
@callback query(connection(), statement(), params(), options :: Keyword.t()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Runs the given statement as a query.

# `query_many`

```elixir
@callback query_many(connection(), statement(), params(), options :: Keyword.t()) ::
  {:ok, term()} | {:error, Exception.t()}
```

Runs the given statement as a multi-result query.

# `stream`

```elixir
@callback stream(connection(), statement(), params(), options :: Keyword.t()) :: Enum.t()
```

Returns a stream that prepares and executes the given query with
`DBConnection`.

# `table_exists_query`

```elixir
@callback table_exists_query(table :: String.t()) :: {iodata(), [term()]}
```

Returns a queryable to check if the given `table` exists.

# `to_constraints`

```elixir
@callback to_constraints(exception :: Exception.t(), options :: Keyword.t()) ::
  Keyword.t()
```

Receives the exception returned by `c:query/4`.

The constraints are in the keyword list and must return the
constraint type, like `:unique`, and the constraint name as
a string, for example:

    [unique: "posts_title_index"]

Must return an empty list if the error does not come
from any constraint.

# `update`

```elixir
@callback update(
  prefix :: String.t(),
  table :: String.t(),
  fields :: [atom()],
  filters :: [atom()],
  returning :: [atom()]
) :: iodata()
```

Returns an UPDATE for the given `fields` in `table` filtered by
`filters` returning the given `returning`.

# `update_all`

```elixir
@callback update_all(query :: Ecto.Query.t()) :: iodata()
```

Receives a query and values to update and must return an UPDATE query.

---

*Consult [api-reference.md](api-reference.md) for complete listing*