Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Provide better documentation for mysqli_multi_query #737

Merged
merged 8 commits into from
Aug 6, 2021
Merged

Provide better documentation for mysqli_multi_query #737

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7622203
Change the description
kamil-tekiela Jun 26, 2021
9ddbf43
Added paragraph about execution sequence
kamil-tekiela Jun 26, 2021
95570a1
Describe how to fetch results
kamil-tekiela Jun 26, 2021
56cfb05
Describe how to implement a blocking loop
kamil-tekiela Jun 26, 2021
b802503
Paraphrased from MySQL docs
kamil-tekiela Jun 26, 2021
ccc18f9
Cleanup examples
kamil-tekiela Jun 26, 2021
327b53e
Update reference/mysqli/mysqli/multi-query.xml
kamil-tekiela Jun 26, 2021
e27ba6a
Link to do-while
kamil-tekiela Jun 26, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
128 changes: 72 additions & 56 deletions reference/mysqli/mysqli/multi-query.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<refnamediv>
<refname>mysqli::multi_query</refname>
<refname>mysqli_multi_query</refname>
<refpurpose>Performs a query on the database</refpurpose>
<refpurpose>Performs one or more queries on the database</refpurpose>
</refnamediv>

<refsect1 role="description">
Expand All @@ -24,11 +24,46 @@
Executes one or multiple queries which are concatenated by a semicolon.
</para>
<para>
To retrieve the resultset from the first query you can use
<function>mysqli_use_result</function> or <function>mysqli_store_result</function>.
All subsequent query results can be processed using
<function>mysqli_more_results</function> and <function>mysqli_next_result</function>.
Queries are sent asynchronously in a single call to the database, but the
database processes them sequentially.
<methodname>mysqli_multi_query</methodname> waits for the first query to
complete before returning control to PHP. The MySQL server will then process
the next query in the sequence. Once the next result is ready, MySQL will wait
for the next execution of <function>mysqli_next_result</function> from PHP.
</para>
<para>
It is recommended to use
<link linkend="control-structures.do.while">do-while</link> to process multiple
queries. The connection will be busy until all queries have completed and
their results are fetched to PHP. No other statement can be issued on the
same connection until all queries are processed.
To proceed to the next query in the sequence, use
<function>mysqli_next_result</function>. If the next result is not ready yet,
mysqli will wait for the response from the MySQL server.
To check if there are more results,
use <function>mysqli_more_results</function>.
</para>
<para>
For queries which produce a result set, such as
<literal>SELECT, SHOW, DESCRIBE</literal> or
<literal>EXPLAIN</literal>,
<function>mysqli_use_result</function> or <function>mysqli_store_result</function>
can be used to retrieve the result set. For queries which do not produce a
result set, the same functions can be used to retrieve information such as
the number of affected rows.
</para>
<tip>
<para>
Executing <literal>CALL</literal> statements for stored procedures can
produce multiple result sets. If the stored procedure contains
<literal>SELECT</literal> statements, the result sets are returned in the
order that they are produced as the procedure executes. In general, the
caller cannot know how many result sets a procedure will return and must be
prepared to retrieve multiple results. The final result from the procedure
is a status result that includes no result set. The status indicates whether
the procedure succeeded or an error occurred.
</para>
</tip>
</refsect1>

<refsect1 role="parameters">
Expand All @@ -40,7 +75,8 @@
<term><parameter>query</parameter></term>
<listitem>
<para>
The query, as a string.
A string containing the queries to be executed.
Multiple queries must be separated by a semicolon.
</para>
<para>
Data inside the query should be <link linkend="mysqli.real-escape-string">properly escaped</link>.
Expand Down Expand Up @@ -68,74 +104,54 @@
<programlisting role="php">
<![CDATA[
<?php
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$mysqli = new mysqli("localhost", "my_user", "my_password", "world");

$query = "SELECT CURRENT_USER();";
$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* execute multi query */
if ($mysqli->multi_query($query)) {
do {
/* store first result set */
if ($result = $mysqli->store_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
$result->free();
$mysqli->multi_query($query);
do {
/* store the result set in PHP */
if ($result = $mysqli->store_result()) {
while ($row = $result->fetch_row()) {
printf("%s\n", $row[0]);
}
/* print divider */
if ($mysqli->more_results()) {
printf("-----------------\n");
}
} while ($mysqli->next_result());
}

/* close connection */
$mysqli->close();
?>
}
/* print divider */
if ($mysqli->more_results()) {
printf("-----------------\n");
}
} while ($mysqli->next_result());
]]>
</programlisting>
<para>&style.procedural;</para>
<programlisting role="php">
<![CDATA[
<?php
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

/* check connection */
if (mysqli_connect_errno()) {
printf("Connect failed: %s\n", mysqli_connect_error());
exit();
}
mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
$link = mysqli_connect("localhost", "my_user", "my_password", "world");

$query = "SELECT CURRENT_USER();";
$query = "SELECT CURRENT_USER();";
$query .= "SELECT Name FROM City ORDER BY ID LIMIT 20, 5";

/* execute multi query */
if (mysqli_multi_query($link, $query)) {
do {
/* store first result set */
if ($result = mysqli_store_result($link)) {
while ($row = mysqli_fetch_row($result)) {
printf("%s\n", $row[0]);
}
mysqli_free_result($result);
}
/* print divider */
if (mysqli_more_results($link)) {
printf("-----------------\n");
mysqli_multi_query($link, $query);
do {
/* store the result set in PHP */
if ($result = mysqli_store_result($link)) {
while ($row = mysqli_fetch_row($result)) {
printf("%s\n", $row[0]);
}
} while (mysqli_next_result($link));
}

/* close connection */
mysqli_close($link);
?>
}
/* print divider */
if (mysqli_more_results($link)) {
printf("-----------------\n");
}
} while (mysqli_next_result($link));
]]>
</programlisting>
&examples.outputs.similar;
Expand Down