From 3742d36be1e1d0d9249ce7e093f4f05ead85b8e8 Mon Sep 17 00:00:00 2001 From: Christoph Michael Becker Date: Fri, 30 Oct 2020 15:45:26 +0000 Subject: [PATCH] Improve transaction examples for mysqli A correct example was provided in begin_transaction() and commit() & rollback are linked. For autocommit the example was expanded to show how one can use autocommit to create transactions. This should also clarify the behaviour of commit in regards to autocommit. A note section was copied from autocommit doc to the other three. Also added simple description of SAVEPOINT and RELEASE SAVEPOINT. Patch contributed by Dharman . git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@351087 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/mysqli/mysqli/autocommit.xml | 137 ++++++++++++++---- reference/mysqli/mysqli/begin-transaction.xml | 100 +++++++++---- reference/mysqli/mysqli/commit.xml | 83 ++--------- reference/mysqli/mysqli/release-savepoint.xml | 11 +- reference/mysqli/mysqli/rollback.xml | 121 ++-------------- reference/mysqli/mysqli/savepoint.xml | 10 +- 6 files changed, 217 insertions(+), 245 deletions(-) diff --git a/reference/mysqli/mysqli/autocommit.xml b/reference/mysqli/mysqli/autocommit.xml index 329592254e..822bc7a1c3 100644 --- a/reference/mysqli/mysqli/autocommit.xml +++ b/reference/mysqli/mysqli/autocommit.xml @@ -57,7 +57,7 @@ &reftitle.notes; - This function doesn't work with non transactional table types (like + This function does not work with non transactional table types (like MyISAM or ISAM). @@ -71,56 +71,139 @@ query("CREATE TABLE IF NOT EXISTS language ( + Code text NOT NULL, + Speakers int(11) NOT NULL + ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;"); -/* turn autocommit on */ -$mysqli->autocommit(TRUE); +/* Turn autocommit off */ +$mysqli->autocommit(false); -if ($result = $mysqli->query("SELECT @@autocommit")) { +$result = $mysqli->query("SELECT @@autocommit"); +$row = $result->fetch_row(); +printf("Autocommit is %s\n", $row[0]); + +try { + /* Prepare insert statement */ + $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)'); + $stmt->bind_param('ss', $language_code, $native_speakers); + + /* Insert some values */ + $language_code = 'DE'; + $native_speakers = 50_123_456; + $stmt->execute(); + $language_code = 'FR'; + $native_speakers = 40_546_321; + $stmt->execute(); + + /* Commit the data in the database. This doesn't set autocommit=true */ + $mysqli->commit(); + print "Committed 2 rows in the database\n"; + + $result = $mysqli->query("SELECT @@autocommit"); $row = $result->fetch_row(); printf("Autocommit is %s\n", $row[0]); - $result->free(); -} -/* close connection */ -$mysqli->close(); -?> + /* Try to insert more values */ + $language_code = 'PL'; + $native_speakers = 30_555_444; + $stmt->execute(); + $language_code = 'DK'; + $native_speakers = 5_222_444; + $stmt->execute(); + + /* Setting autocommit=true will trigger a commit */ + $mysqli->autocommit(true); + + print "Committed 2 row in the database\n"; +} catch (mysqli_sql_exception $exception) { + $mysqli->rollback(); + + throw $exception; +} ]]> &style.procedural; + /* Try to insert more values */ + $language_code = 'PL'; + $native_speakers = 30_555_444; + mysqli_stmt_execute($stmt); + $language_code = 'DK'; + $native_speakers = 5_222_444; + mysqli_stmt_execute($stmt); + + /* Setting autocommit=true will trigger a commit */ + mysqli_autocommit($mysqli, true); + + print "Committed 2 row in the database\n"; +} catch (mysqli_sql_exception $exception) { + mysqli_rollback($mysqli); + + throw $exception; +} ]]> &examples.outputs; diff --git a/reference/mysqli/mysqli/begin-transaction.xml b/reference/mysqli/mysqli/begin-transaction.xml index 15b11d6c22..f0a078e100 100644 --- a/reference/mysqli/mysqli/begin-transaction.xml +++ b/reference/mysqli/mysqli/begin-transaction.xml @@ -84,48 +84,96 @@ + + &reftitle.notes; + + + This function does not work with non transactional table types (like + MyISAM or ISAM). + + + + &reftitle.examples; - - <methodname>$mysqli->begin_transaction</methodname> example + + <methodname>mysqli::begin_transaction</methodname> example &style.oop; connect_errno) { - printf("Connect failed: %s\n", $mysqli->connect_error); - exit(); +/* Tell mysqli to throw an exception if an error occurs */ +mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT); + +$mysqli = new mysqli("localhost", "my_user", "my_password", "world"); + +/* The table engine has to support transactions */ +$mysqli->query("CREATE TABLE IF NOT EXISTS language ( + Code text NOT NULL, + Speakers int(11) NOT NULL + ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;"); + +/* Start transaction */ +$mysqli->begin_transaction(); + +try { + /* Insert some values */ + $mysqli->query("INSERT INTO language(Code, Speakers) VALUES ('DE', 42000123)"); + + /* Try to insert invalid values */ + $language_code = 'FR'; + $native_speakers = 'Unknown'; + $stmt = $mysqli->prepare('INSERT INTO language(Code, Speakers) VALUES (?,?)'); + $stmt->bind_param('ss', $language_code, $native_speakers); + $stmt->execute(); + + /* If code reaches this point without errors then commit the data in the database */ + $mysqli->commit(); +} catch (mysqli_sql_exception $exception) { + $mysqli->rollback(); + + throw $exception; } - -$mysqli->begin_transaction(MYSQLI_TRANS_START_READ_ONLY); - -$mysqli->query("SELECT first_name, last_name FROM actor"); -$mysqli->commit(); - -$mysqli->close(); -?> ]]> &style.procedural; ]]> diff --git a/reference/mysqli/mysqli/commit.xml b/reference/mysqli/mysqli/commit.xml index 91896cba05..2a819b004a 100644 --- a/reference/mysqli/mysqli/commit.xml +++ b/reference/mysqli/mysqli/commit.xml @@ -59,6 +59,16 @@ + + &reftitle.notes; + + + This function does not work with non transactional table types (like + MyISAM or ISAM). + + + + &reftitle.changelog; @@ -86,76 +96,9 @@ &reftitle.examples; - - <methodname>mysqli::commit</methodname> example - &style.oop; - -query("CREATE TABLE Language LIKE CountryLanguage"); - -/* set autocommit to off */ -$mysqli->autocommit(FALSE); - -/* Insert some values */ -$mysqli->query("INSERT INTO Language VALUES ('DEU', 'Bavarian', 'F', 11.2)"); -$mysqli->query("INSERT INTO Language VALUES ('DEU', 'Swabian', 'F', 9.4)"); - -/* commit transaction */ -if (!$mysqli->commit()) { - print("Transaction commit failed\n"); - exit(); -} - -/* drop table */ -$mysqli->query("DROP TABLE Language"); - -/* close connection */ -$mysqli->close(); -?> -]]> - - &style.procedural; - - -]]> - - + + See the mysqli::begin_transaction example. + diff --git a/reference/mysqli/mysqli/release-savepoint.xml b/reference/mysqli/mysqli/release-savepoint.xml index 54275e0bdc..71fe00ae49 100644 --- a/reference/mysqli/mysqli/release-savepoint.xml +++ b/reference/mysqli/mysqli/release-savepoint.xml @@ -1,6 +1,5 @@ - mysqli::release_savepoint @@ -22,11 +21,9 @@ stringname - + This function is identical to executing $mysqli->query("RELEASE SAVEPOINT `$name`");. + This function does not trigger commit or rollback. - - &warn.undocumented.func; - @@ -38,7 +35,7 @@ name - + The identifier of the savepoint. @@ -57,7 +54,7 @@ &reftitle.seealso; - mysqli_rollback + mysqli_savepoint diff --git a/reference/mysqli/mysqli/rollback.xml b/reference/mysqli/mysqli/rollback.xml index dbc1b4f419..afafc4aeb8 100644 --- a/reference/mysqli/mysqli/rollback.xml +++ b/reference/mysqli/mysqli/rollback.xml @@ -59,6 +59,16 @@ + + &reftitle.notes; + + + This function does not work with non transactional table types (like + MyISAM or ISAM). + + + + &reftitle.changelog; @@ -86,114 +96,9 @@ &reftitle.examples; - - <methodname>mysqli::rollback</methodname> example - &style.oop; - -autocommit(FALSE); - -$mysqli->query("CREATE TABLE myCity LIKE City"); -$mysqli->query("ALTER TABLE myCity Type=InnoDB"); -$mysqli->query("INSERT INTO myCity SELECT * FROM City LIMIT 50"); - -/* commit insert */ -$mysqli->commit(); - -/* delete all rows */ -$mysqli->query("DELETE FROM myCity"); - -if ($result = $mysqli->query("SELECT COUNT(*) FROM myCity")) { - $row = $result->fetch_row(); - printf("%d rows in table myCity.\n", $row[0]); - /* Free result */ - $result->close(); -} - -/* Rollback */ -$mysqli->rollback(); - -if ($result = $mysqli->query("SELECT COUNT(*) FROM myCity")) { - $row = $result->fetch_row(); - printf("%d rows in table myCity (after rollback).\n", $row[0]); - /* Free result */ - $result->close(); -} - -/* Drop table myCity */ -$mysqli->query("DROP TABLE myCity"); - -$mysqli->close(); -?> -]]> - - &style.procedural; - - -]]> - - &examples.outputs; - - - - + + See the mysqli::begin_transaction example. + diff --git a/reference/mysqli/mysqli/savepoint.xml b/reference/mysqli/mysqli/savepoint.xml index 7b0bfc2d74..dde2307dcb 100644 --- a/reference/mysqli/mysqli/savepoint.xml +++ b/reference/mysqli/mysqli/savepoint.xml @@ -1,6 +1,5 @@ - mysqli::savepoint @@ -22,11 +21,8 @@ stringname - + This function is identical to executing $mysqli->query("SAVEPOINT `$name`"); - - &warn.undocumented.func; - @@ -38,7 +34,7 @@ name - + The identifier of the savepoint. @@ -57,7 +53,7 @@ &reftitle.seealso; - mysqli_commit + mysqli_release_savepoint