defmodule ExSQL.Error do
  @moduledoc """
  Exception raised (internally) and returned (externally) for SQL errors.

  Public API functions return `{:error, %ExSQL.Error{}}` rather than raising;
  the bang variants (`ExSQL.execute!/2`) raise it.
  """

  defexception [:message, :line, :db]

  @typedoc """
  `db` is internal plumbing: `OR FAIL` / `OR ROLLBACK` conflict resolution
  attaches the database state the failed statement leaves behind (partial
  changes kept, or the transaction rolled back). It is scrubbed before
  errors reach the public API.
  """
  @type t :: %__MODULE__{
          message: String.t(),
          line: pos_integer() | nil,
          db: ExSQL.Database.t() | nil
        }

  @impl true
  def message(%__MODULE__{message: message, line: nil}), do: message
  @impl true
  def message(%__MODULE__{message: message, line: line}), do: "#{message} (line #{line})"
end