# `Selecto.Executor`

Query execution engine for Selecto.

Handles execution of generated SQL queries through configured adapter or repo
contexts, with proper error handling and connection management.

# `connection_info`

Get connection statistics for monitoring.

Returns information about the current connection state.

# `execute`

```elixir
@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

# `execute_one`

```elixir
@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

# `execute_stream`

```elixir
@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_with_adapter`

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_with_connection_pool`

Execute query using connection pool.

# `execute_with_ecto_fallback`

Fallback execution when adapter-native repo execution is unavailable.

Creates a temporary adapter-managed connection from repo configuration.

# `execute_with_ecto_repo`

Execute query using an Ecto repository.

Routes repository execution through the configured adapter.

# `execute_with_metadata`

```elixir
@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_with_postgrex`

Execute query using the default PostgreSQL adapter.

# `validate_connection`

Validate connection before executing query.

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

---

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