Method execute

src/adapter/src/client.rs:771–829

(
        &mut self,
        portal_name: String,
        cancel_future: impl Future<Output = std::io::Error> + Send,
        outer_ctx_extra: Option<ExecuteContextGuard>,
    )

    /// triggering the execution of the underlying query.
    #[mz_ore::instrument(level = "debug")]
    pub async fn execute(
        &mut self,
        portal_name: String,
        cancel_future: impl Future<Output = std::io::Error> + Send,
        outer_ctx_extra: Option<ExecuteContextGuard>,
    ) -> Result<(ExecuteResponse, Instant), AdapterError> {
        let execute_started = Instant::now();

        let mut outer_ctx_extra = outer_ctx_extra;

        // Unroll SQL `EXECUTE <prepared> (...)` so the inner statement
        // flows through `try_frontend_peek` below, rather than being
        // re-dispatched via `Command::Execute` from the coordinator's
        // `Plan::Execute` handler. Without this, a prepared statement
        // would route differently from the same statement issued
        // directly.
        //
        // On a successful unroll, `unroll_sql_execute` also returns a
        // catalog snapshot (threaded through to avoid taking a second
        // one) and begins EXECUTE-level statement logging on the outer
        // portal — so `mz_statement_execution_history` records
        // `EXECUTE foo (...)`, not the inner SQL — installing the
        // resulting `ExecuteContextGuard` into `outer_ctx_extra`.
        let (portal_name, catalog) = self
            .unroll_sql_execute(portal_name, &mut outer_ctx_extra)
            .await?;

        // Attempt peek sequencing in the session task.
        // If unsupported, fall back to the Coordinator path.
        // TODO(peek-seq): wire up cancel_future
        let peek_result = self
            .try_frontend_peek(&portal_name, catalog, &mut outer_ctx_extra)
            .await?;
        if let Some(resp) = peek_result {
            debug!("frontend peek succeeded");
            // Frontend peek handled the execution and retired outer_ctx_extra if it existed.
            // No additional work needed here.
            return Ok((resp, execute_started));
        } else {
            debug!("frontend peek did not happen, falling back to `Command::Execute`");
            // If we bailed out, outer_ctx_extra is still present (if it was originally).
            // `Command::Execute` will handle it.
            // (This is not true if we bailed out _after_ the frontend peek sequencing has already
            // begun its own statement logging. That case would be a bug.)
        }

        let response = self
            .send_with_cancel(
                |tx, session| Command::Execute {
                    portal_name,
                    session,
                    tx,
                    outer_ctx_extra,
                },
                cancel_future,
            )
            .await?;
        Ok((response, execute_started))