client: add Stmt.ExecuteProcedureMultiResults for multi-result stored procedures

[nzin-alayacare]

Summary

Add (*Stmt).ExecuteProcedureMultiResults and the StmtProcedureMultiResultForward callback type to client/stmt.go.

Closes #1162

Motivation

(*Stmt).Execute reads a single result via readResult(true) and stops. When a stored procedure returns multiple result sets (e.g., a CALL with OUT parameters or multiple SELECT statements inside), the server sets SERVER_MORE_RESULTS_EXISTS in intermediate result statuses. Calling Execute in this case leaves subsequent packets buffered on the connection, corrupting its state.

The text-protocol equivalent Conn.ExecuteMultiple already handles this correctly by looping until the flag is clear. This PR adds the same capability for prepared statements (COM_STMT_EXECUTE), which is the path taken by Connector/J and other JDBC drivers for CallableStatement.

New API

// StmtProcedureMultiResultForward is called once per logical result returned by
// COM_STMT_EXECUTE. When err is non-nil, res is nil.
type StmtProcedureMultiResultForward func(res *mysql.Result, err error) error

// ExecuteProcedureMultiResults runs COM_STMT_EXECUTE and reads every response
// until SERVER_MORE_RESULTS_EXISTS is clear.  forward is called for each
// result; the loop keeps draining even after forward returns non-nil so that
// unread packets do not corrupt the connection state.
func (s *Stmt) ExecuteProcedureMultiResults(
    args []any,
    forward StmtProcedureMultiResultForward,
) (*mysql.Result, error)

Design notes

• Drain-on-error: the loop does not stop when forward returns an error because leaving unread results on the wire would corrupt the connection. Instead the forward error is saved and returned only after all results have been consumed — identical to ExecuteMultiple semantics.
• Synthetic return value: a StreamingMultiple / StreamingDone result is returned on success so callers can pass it to server.Conn.WriteValue without additional handling.
• Nil check on callback: returns an immediate error rather than panic.

Notes

• Pure additive change — no existing API is modified.
• Requires CLIENT_PS_MULTI_RESULTS to be negotiated (included in server default capabilities since server: advertise CLIENT_MULTI_RESULTS, CLIENT_PS_MULTI_RESULTS in default capabilities #1155).
• Tested in production at alayacare/castledm.

Made with Cursor

[gemini-code-assist]

Code Review

This pull request adds the ExecuteProcedureMultiResults method to the Stmt struct in client/stmt.go to support executing stored procedures that return multiple result sets. The review feedback suggests improving the API's usability and consistency by making the args parameter variadic and placing the forward callback first, as well as initializing the synthetic resultset with 0 fields instead of 1.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[lance6716]

rest lgtm