next_result

When you send several SQL statements to MySQL in one call with mysqli_multi_query(), the server hands them back to you one result set at a time. mysqli_next_result() is the function that moves you from the current result set to the next one, so you can loop over all of them. This article explains what the function returns, the parameters it takes, the common pitfalls, and how to use it in both the procedural and object-oriented MySQLi styles.

What mysqli_next_result() does

mysqli_next_result() prepares the next result set from a previous call to mysqli_multi_query() and makes it available for retrieval functions such as mysqli_store_result() or mysqli_fetch_assoc(). Internally, MySQL buffers all the result sets of a multi-query; this function advances the internal pointer by one.

Important: a single call to mysqli_next_result() only moves you forward one step. To process every statement, you call it inside a loop until there are no results left.

Syntax

// Procedural style
mysqli_next_result(mysqli $mysql): bool

// Object-oriented style
$mysqli->next_result(): bool

Parameters

• $mysql (procedural only) — the connection object returned by mysqli_connect(). In OOP style this is the object you call the method on.

Return value

It returns a boolean:

• true — the next result set was prepared successfully (or there were no more results and no error).
• false — there was an error in the next statement, or the previous query had no buffered results to advance to.

To tell "there are no more results" apart from "the next statement failed", pair it with mysqli_more_results(): if mysqli_more_results() is true but mysqli_next_result() returns false, the next statement raised an error.

How to use mysqli_next_result() (procedural style)

Execute the batch with mysqli_multi_query(), process the first result set, then loop while there are more results, advancing with mysqli_next_result() each pass:

<?php
$mysqli = mysqli_connect("localhost", "username", "password", "database");

if (!$mysqli) {
    die("Connection failed: " . mysqli_connect_error());
}

$query  = "SELECT name FROM users LIMIT 1;";
$query .= "SELECT title FROM posts LIMIT 1;";

if (mysqli_multi_query($mysqli, $query)) {
    do {
        // mysqli_store_result() returns false for statements that
        // produce no rows (INSERT, UPDATE, DELETE), so guard with if.
        if ($result = mysqli_store_result($mysqli)) {
            while ($row = mysqli_fetch_assoc($result)) {
                print_r($row);
            }
            mysqli_free_result($result);
        }
        // Stop when there are no more results; otherwise advance.
    } while (mysqli_more_results($mysqli) && mysqli_next_result($mysqli));
} else {
    echo "Multi-query failed: " . mysqli_error($mysqli);
}

mysqli_close($mysqli);
?>

The do...while condition is the key idea: mysqli_more_results() checks whether another set exists, and mysqli_next_result() actually advances to it. Because && short-circuits, mysqli_next_result() is only called when another result genuinely exists, which avoids the warning you would otherwise get when calling it past the last set.

Object-oriented style

The same logic with the OOP API reads a little cleaner:

<?php
$mysqli = new mysqli("localhost", "username", "password", "database");

if ($mysqli->connect_errno) {
    die("Connection failed: " . $mysqli->connect_error);
}

$sql  = "SELECT name FROM users LIMIT 1;";
$sql .= "SELECT title FROM posts LIMIT 1;";

if ($mysqli->multi_query($sql)) {
    do {
        if ($result = $mysqli->store_result()) {
            while ($row = $result->fetch_assoc()) {
                print_r($row);
            }
            $result->free();
        }
    } while ($mysqli->more_results() && $mysqli->next_result());
}

$mysqli->close();
?>

Common gotchas

• Always drain the queue. If you run another query while result sets from a previous mysqli_multi_query() are still pending, MySQLi throws "Commands out of sync". Loop with mysqli_next_result() until mysqli_more_results() is false before issuing a new query.
• Forgetting mysqli_store_result() for non-SELECT statements. Statements like INSERT produce no result set, so mysqli_store_result() returns false — that is expected, not an error. The if ($result = ...) guard handles it.
• Multi-query is a SQL-injection risk. Only ever pass trusted, server-controlled SQL to mysqli_multi_query(). Never concatenate user input into a multi-statement string; use prepared statements for user data instead.

Conclusion

mysqli_next_result() is the function that lets you walk through every result set returned by a single mysqli_multi_query() call. Used together with mysqli_more_results() inside a do...while loop, it lets you process each statement's output safely and keeps the connection from falling out of sync. For more on the surrounding workflow, see mysqli_multi_query() and mysqli_fetch_assoc().

Practice