defmodule Ecto.Adapters.SQL.Connection do
  @moduledoc """
  Specifies the behaviour to be implemented by all SQL connections.
  """

  @typedoc "The query name"
  @type name :: String.t

  @typedoc "The SQL statement"
  @type statement :: String.t

  @typedoc "The cached query which is a DBConnection Query"
  @type cached :: map

  @type connection :: DBConnection.conn()
  @type params :: [term]

  @doc """
  Receives options and returns `DBConnection` supervisor child
  specification.
  """
  @callback child_spec(options :: Keyword.t) :: :supervisor.child_spec() | {module, Keyword.t}

  @doc """
  Prepares and executes the given query with `DBConnection`.
  """
  @callback prepare_execute(connection, name, statement, params, options :: Keyword.t) ::
              {:ok, cached, term} | {:error, Exception.t}

  @doc """
  Executes a cached query.
  """
  @callback execute(connection, cached, params, options :: Keyword.t) ::
              {:ok, cached, term} | {:ok, term} | {:error | :reset, Exception.t}

  @doc """
  Runs the given statement as a query.
  """
  @callback query(connection, statement, params, options :: Keyword.t) ::
              {:ok, term} | {:error, Exception.t}

  @doc """
  Runs the given statement as a multi-result query.
  """
  @callback query_many(connection, statement, params, options :: Keyword.t) ::
              {:ok, term} | {:error, Exception.t}

  @doc """
  Returns a stream that prepares and executes the given query with
  `DBConnection`.
  """
  @callback stream(connection, statement, params, options :: Keyword.t) ::
              Enum.t

  @doc """
  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.
  """
  @callback to_constraints(exception :: Exception.t, options :: Keyword.t) :: Keyword.t

  ## Queries

  @doc """
  Receives a query and must return a SELECT query.
  """
  @callback all(query :: Ecto.Query.t) :: iodata

  @doc """
  Receives a query and values to update and must return an UPDATE query.
  """
  @callback update_all(query :: Ecto.Query.t) :: iodata

  @doc """
  Receives a query and must return a DELETE query.
  """
  @callback delete_all(query :: Ecto.Query.t) :: iodata

  @doc """
  Returns an INSERT for the given `rows` in `table` returning
  the given `returning`.
  """
  @callback insert(prefix ::String.t, table :: String.t,
                   header :: [atom], rows :: [[atom | nil]],
                   on_conflict :: Ecto.Adapter.Schema.on_conflict, returning :: [atom],
                   placeholders :: [term]) :: iodata

  @doc """
  Returns an UPDATE for the given `fields` in `table` filtered by
  `filters` returning the given `returning`.
  """
  @callback update(prefix :: String.t, table :: String.t, fields :: [atom],
                   filters :: [atom], returning :: [atom]) :: iodata

  @doc """
  Returns a DELETE for the `filters` returning the given `returning`.
  """
  @callback delete(prefix :: String.t, table :: String.t,
                   filters :: [atom], returning :: [atom]) :: iodata

  @doc """
  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.
  """
  @callback explain_query(connection, query :: String.t, params :: Keyword.t, opts :: Keyword.t) ::
              {:ok, term} | {:error, Exception.t}

  ## DDL

  @doc """
  Receives a DDL command and returns a query that executes it.
  """
  @callback execute_ddl(command :: Ecto.Adapter.Migration.command) :: String.t | [iodata]

  @doc """
  Receives a query result and returns a list of logs.
  """
  @callback ddl_logs(result :: term) :: [{Logger.level, Logger.message, Logger.metadata}]

  @doc """
  Returns a queryable to check if the given `table` exists.
  """
  @callback table_exists_query(table :: String.t) :: {iodata, [term]}
end