Get connection statistics for monitoring.

Returns information about the current connection state.

@spec execute(Selecto.Types.t(), Selecto.Types.execute_options()) ::
  Selecto.Types.safe_execute_result()

Execute a query and return results with standardized error handling.

Parameters

• selecto - The Selecto struct containing connection and query info
• opts - Execution options (currently unused but reserved for future use)

Returns

• {:ok, {rows, columns, aliases}} - Successful execution with results
• {:error, %Selecto.Error{}} - Execution failure with detailed error

Examples

case Selecto.Executor.execute(selecto) do
  {:ok, {rows, columns, aliases}} ->
    # Process successful results
    handle_results(rows, columns, aliases)
  {:error, error} ->
    # Handle database error
    Logger.error("Query failed: #{inspect(error)}")
end

@spec execute_one(Selecto.Types.t(), Selecto.Types.execute_options()) ::
  Selecto.Types.safe_execute_one_result()

Execute a query expecting exactly one row, returning {:ok, row} or {:error, reason}.

Useful for queries that should return a single record (e.g., with LIMIT 1 or aggregate functions). Returns an error if zero rows or multiple rows are returned.

Examples

case Selecto.Executor.execute_one(selecto) do
  {:ok, row} ->
    # Handle single row result
    process_single_result(row)
  {:error, :no_results} ->
    # Handle case where no rows were found
  {:error, :multiple_results} ->
    # Handle case where multiple rows were found
  {:error, error} ->
    # Handle database or other errors
end

@spec execute_stream(
  Selecto.Types.t(),
  keyword()
) :: Selecto.Types.safe_execute_stream_result()

Execute a query as a stream of {row, columns, aliases} tuples.

Current stream support:

• The default PostgreSQL adapter via adapter-owned stream hooks
• Custom adapters that implement stream/4

Execute query using a database adapter.

This function delegates to the adapter's execute/4 function, allowing for different database types like SQLite, MySQL, etc.

Execute query using connection pool.

Fallback execution when adapter-native repo execution is unavailable.

Creates a temporary adapter-managed connection from repo configuration.

Execute query using an Ecto repository.

Routes repository execution through the configured adapter.

@spec execute_with_metadata(Selecto.Types.t(), Selecto.Types.execute_options()) ::
  {:ok, Selecto.Types.execute_result(), map()} | {:error, Selecto.Error.t()}

Execute a query and return results with metadata including SQL, params, and execution time.

Parameters

• selecto - The Selecto struct containing connection and query info
• opts - Execution options

Returns

• {:ok, result, metadata} - Successful execution with results and metadata
• {:error, error} - Execution failure with detailed error

The metadata map includes:

• :sql - The generated SQL query string
• :params - The query parameters
• :execution_time - Query execution time in milliseconds

Examples

case Selecto.Executor.execute_with_metadata(selecto) do
  {:ok, {rows, columns, aliases}, _meta} ->
    # Process successful results with metadata
    handle_results(rows, columns, aliases)
  {:error, error} ->
    # Handle database error
    Logger.error("Query failed: #{inspect(error)}")
end

Execute query using the default PostgreSQL adapter.

Validate connection before executing query.

Returns :ok if connection is valid, {:error, reason} otherwise.