317 lines
13 KiB
HTML
317 lines
13 KiB
HTML
<!DOCTYPE html>
|
|
<html><head>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
|
|
<link href="sqlite.css" rel="stylesheet">
|
|
<title>Transaction</title>
|
|
<!-- path= -->
|
|
</head>
|
|
<body>
|
|
<div class=nosearch>
|
|
<a href="index.html">
|
|
<img class="logo" src="images/sqlite370_banner.gif" alt="SQLite" border="0">
|
|
</a>
|
|
<div><!-- IE hack to prevent disappearing logo --></div>
|
|
<div class="tagline desktoponly">
|
|
Small. Fast. Reliable.<br>Choose any three.
|
|
</div>
|
|
<div class="menu mainmenu">
|
|
<ul>
|
|
<li><a href="index.html">Home</a>
|
|
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
|
|
<li class='wideonly'><a href='about.html'>About</a>
|
|
<li class='desktoponly'><a href="docs.html">Documentation</a>
|
|
<li class='desktoponly'><a href="download.html">Download</a>
|
|
<li class='wideonly'><a href='copyright.html'>License</a>
|
|
<li class='desktoponly'><a href="support.html">Support</a>
|
|
<li class='desktoponly'><a href="prosupport.html">Purchase</a>
|
|
<li class='search' id='search_menubutton'>
|
|
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
|
|
</ul>
|
|
</div>
|
|
<div class="menu submenu" id="submenu">
|
|
<ul>
|
|
<li><a href='about.html'>About</a>
|
|
<li><a href='docs.html'>Documentation</a>
|
|
<li><a href='download.html'>Download</a>
|
|
<li><a href='support.html'>Support</a>
|
|
<li><a href='prosupport.html'>Purchase</a>
|
|
</ul>
|
|
</div>
|
|
<div class="searchmenu" id="searchmenu">
|
|
<form method="GET" action="search">
|
|
<select name="s" id="searchtype">
|
|
<option value="d">Search Documentation</option>
|
|
<option value="c">Search Changelog</option>
|
|
</select>
|
|
<input type="text" name="q" id="searchbox" value="">
|
|
<input type="submit" value="Go">
|
|
</form>
|
|
</div>
|
|
</div>
|
|
<script>
|
|
function toggle_div(nm) {
|
|
var w = document.getElementById(nm);
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
}else{
|
|
w.style.display = "block";
|
|
}
|
|
}
|
|
function toggle_search() {
|
|
var w = document.getElementById("searchmenu");
|
|
if( w.style.display=="block" ){
|
|
w.style.display = "none";
|
|
} else {
|
|
w.style.display = "block";
|
|
setTimeout(function(){
|
|
document.getElementById("searchbox").focus()
|
|
}, 30);
|
|
}
|
|
}
|
|
function div_off(nm){document.getElementById(nm).style.display="none";}
|
|
window.onbeforeunload = function(e){div_off("submenu");}
|
|
/* Disable the Search feature if we are not operating from CGI, since */
|
|
/* Search is accomplished using CGI and will not work without it. */
|
|
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
|
|
document.getElementById("search_menubutton").style.display = "none";
|
|
}
|
|
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
|
|
function hideorshow(btn,obj){
|
|
var x = document.getElementById(obj);
|
|
var b = document.getElementById(btn);
|
|
if( x.style.display!='none' ){
|
|
x.style.display = 'none';
|
|
b.innerHTML='show';
|
|
}else{
|
|
x.style.display = '';
|
|
b.innerHTML='hide';
|
|
}
|
|
return false;
|
|
}
|
|
</script>
|
|
</div>
|
|
<div class=fancy>
|
|
<div class=nosearch>
|
|
<div class="fancy_title">
|
|
Transaction
|
|
</div>
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<h1 id="transaction_control_syntax"><span>1. </span>Transaction Control Syntax</h1>
|
|
|
|
<p><b><a href="syntax/begin-stmt.html">begin-stmt:</a></b>
|
|
<button id='x2017' onclick='hideorshow("x2017","x2018")'>hide</button></p>
|
|
<div id='x2018' class='imgcontainer'>
|
|
<img alt="syntax diagram begin-stmt" src="images/syntax/begin-stmt.gif" />
|
|
</div>
|
|
<p><b><a href="syntax/commit-stmt.html">commit-stmt:</a></b>
|
|
<button id='x2019' onclick='hideorshow("x2019","x2020")'>hide</button></p>
|
|
<div id='x2020' class='imgcontainer'>
|
|
<img alt="syntax diagram commit-stmt" src="images/syntax/commit-stmt.gif" />
|
|
</div>
|
|
<p><b><a href="syntax/rollback-stmt.html">rollback-stmt:</a></b>
|
|
<button id='x2021' onclick='hideorshow("x2021","x2022")'>hide</button></p>
|
|
<div id='x2022' class='imgcontainer'>
|
|
<img alt="syntax diagram rollback-stmt" src="images/syntax/rollback-stmt.gif" />
|
|
</div>
|
|
|
|
|
|
<h1 id="transactions"><span>2. </span>Transactions</h1>
|
|
|
|
<p>
|
|
No reads or writes occur except within a transaction.
|
|
Any command that accesses the database (basically, any SQL command,
|
|
except a few <a href="pragma.html#syntax">PRAGMA</a> statements)
|
|
will automatically start a transaction if
|
|
one is not already in effect. Automatically started transactions
|
|
are committed when the last SQL statement finishes.
|
|
</p>
|
|
|
|
<p>
|
|
Transactions can be started manually using the BEGIN
|
|
command. Such transactions usually persist until the next
|
|
COMMIT or ROLLBACK command. But a transaction will also
|
|
ROLLBACK if the database is closed or if an error occurs
|
|
and the ROLLBACK conflict resolution algorithm is specified.
|
|
See the documentation on the <a href="lang_conflict.html">ON CONFLICT</a>
|
|
clause for additional information about the ROLLBACK
|
|
conflict resolution algorithm.
|
|
</p>
|
|
|
|
<p>
|
|
END TRANSACTION is an alias for COMMIT.
|
|
</p>
|
|
|
|
<p> Transactions created using BEGIN...COMMIT do not nest.
|
|
For nested transactions, use the <a href="lang_savepoint.html">SAVEPOINT</a> and <a href="lang_savepoint.html">RELEASE</a> commands.
|
|
The "TO SAVEPOINT <span class='yyterm'>name</span>" clause of the ROLLBACK command shown
|
|
in the syntax diagram above is only applicable to <a href="lang_savepoint.html">SAVEPOINT</a>
|
|
transactions. An attempt to invoke the BEGIN command within
|
|
a transaction will fail with an error, regardless of whether
|
|
the transaction was started by <a href="lang_savepoint.html">SAVEPOINT</a> or a prior BEGIN.
|
|
The COMMIT command and the ROLLBACK command without the TO clause
|
|
work the same on <a href="lang_savepoint.html">SAVEPOINT</a> transactions as they do with transactions
|
|
started by BEGIN.</p>
|
|
|
|
<h2 id="read_transactions_versus_write_transactions"><span>2.1. </span>Read transactions versus write transactions</h2>
|
|
|
|
<p>SQLite supports multiple simultaneous read transactions
|
|
coming from separate database connections, possibly in separate
|
|
threads or processes, but only one simultaneous write transaction.
|
|
</p><p>
|
|
|
|
</p><p>A read transaction is used for reading only. A write transaction
|
|
allows both reading and writing. A read transaction is started
|
|
by a SELECT statement, and a write transaction is started by
|
|
statements like CREATE, DELETE, DROP, INSERT, or UPDATE (collectively
|
|
"write statements"). If a write statement occurs while
|
|
a read transaction is active, then the read transaction is upgraded
|
|
to a write transaction if possible. If some other database connection
|
|
has already modified the database or is already in the process of
|
|
modifying the database, then upgrading to a write transaction is
|
|
not possible and the write statement will fail with <a href="rescode.html#busy">SQLITE_BUSY</a>.
|
|
</p>
|
|
|
|
<p>
|
|
While a read transaction is active, any changes to the database that
|
|
are implemented by separate database connections will not be seen
|
|
by the database connection that started the read transaction. If database
|
|
connection X is holding a read transaction, it is possible that some
|
|
other database connection Y might change the content of the database
|
|
while X's transaction is still open, however X will not be able to see
|
|
those changes until after the transaction ends. While its read
|
|
transaction is active, X will continue to see an historic snapshot of
|
|
the database prior to the changes implemented by Y.
|
|
</p>
|
|
|
|
|
|
<a name="immediate"></a>
|
|
|
|
<h2 id="deferred_immediate_and_exclusive_transactions"><span>2.2. </span>DEFERRED, IMMEDIATE, and EXCLUSIVE transactions</h2>
|
|
|
|
<p>
|
|
Transactions can be DEFERRED, IMMEDIATE, or EXCLUSIVE.
|
|
The default transaction behavior is DEFERRED.
|
|
</p>
|
|
|
|
<p>
|
|
DEFERRED means that the transaction does not actually
|
|
start until the database is first accessed. Internally,
|
|
the BEGIN DEFERRED statement merely sets a flag on the database
|
|
connection that turns off the automatic commit that would normally
|
|
occur when the last statement finishes. This causes the transaction
|
|
that is automatically started to persist until an explicit
|
|
COMMIT or ROLLBACK or until a rollback is provoked by an error
|
|
or an ON CONFLICT ROLLBACK clause. If the first statement after
|
|
BEGIN DEFERRED is a SELECT, then a read transaction is started.
|
|
Subsequent write statements will upgrade the transaction to a
|
|
write transaction if possible, or return SQLITE_BUSY. If the
|
|
first statement after BEGIN DEFERRED is a write statement, then
|
|
a write transaction is started.
|
|
</p>
|
|
|
|
<p>
|
|
IMMEDIATE cause the database connection to start a new write
|
|
immediately, without waiting for a write statement. The
|
|
BEGIN IMMEDIATE might fail with <a href="rescode.html#busy">SQLITE_BUSY</a> if another write
|
|
transaction is already active on another database connection.
|
|
</p>
|
|
|
|
<p>
|
|
EXCLUSIVE is similar to IMMEDIATE in that a write transaction
|
|
is started immediately. EXCLUSIVE and IMMEDIATE are the same
|
|
in <a href="wal.html">WAL mode</a>, but in other journaling modes, EXCLUSIVE prevents
|
|
other database connections from reading the database while the
|
|
transaction is underway.
|
|
</p>
|
|
|
|
<h2 id="implicit_versus_explicit_transactions"><span>2.3. </span>Implicit versus explicit transactions</h2>
|
|
|
|
<p>
|
|
An implicit transaction (a transaction that is started automatically,
|
|
not a transaction started by BEGIN) is committed automatically when
|
|
the last active statement finishes. A statement finishes when its
|
|
last cursor closes, which is guaranteed to happen when the
|
|
prepared statement is <a href="c3ref/reset.html">reset</a> or
|
|
<a href="c3ref/finalize.html">finalized</a>. Some statements might "finish"
|
|
for the purpose of transaction control prior to being reset or finalized,
|
|
but there is no guarantee of this. The only way to ensure that a
|
|
statement has "finished" is to invoke <a href="c3ref/reset.html">sqlite3_reset()</a> or
|
|
<a href="c3ref/finalize.html">sqlite3_finalize()</a> on that statement. An open <a href="c3ref/blob.html">sqlite3_blob</a> used for
|
|
incremental BLOB I/O also counts as an unfinished statement.
|
|
The <a href="c3ref/blob.html">sqlite3_blob</a> finishes when it is <a href="c3ref/blob_close.html">closed</a>.
|
|
</p>
|
|
|
|
<p>
|
|
The explicit COMMIT command runs immediately, even if there are
|
|
pending <a href="lang_select.html">SELECT</a> statements. However, if there are pending
|
|
write operations, the COMMIT command
|
|
will fail with an error code <a href="rescode.html#busy">SQLITE_BUSY</a>.
|
|
</p>
|
|
|
|
<p>
|
|
An attempt to execute COMMIT might also result in an <a href="rescode.html#busy">SQLITE_BUSY</a> return code
|
|
if an another thread or process has an open read connection.
|
|
When COMMIT fails in this
|
|
way, the transaction remains active and the COMMIT can be retried later
|
|
after the reader has had a chance to clear.
|
|
</p>
|
|
|
|
<p>
|
|
In very old versions of SQLite (before version 3.7.11 - 2012-03-20)
|
|
the ROLLBACK will fail with an error code
|
|
<a href="rescode.html#busy">SQLITE_BUSY</a> if there are any pending queries. In more recent
|
|
versions of SQLite, the ROLLBACK will proceed and pending statements
|
|
will often be aborted, causing them to return an <a href="rescode.html#abort">SQLITE_ABORT</a> or
|
|
<a href="rescode.html#abort_rollback">SQLITE_ABORT_ROLLBACK</a> error.
|
|
In SQLite version 3.8.8 (2015-01-16) and later,
|
|
a pending read will continue functioning
|
|
after the ROLLBACK as long as the ROLLBACK does not modify the database
|
|
schema.
|
|
</p>
|
|
|
|
<p>
|
|
If <a href="pragma.html#pragma_journal_mode">PRAGMA journal_mode</a> is set to OFF (thus disabling the rollback journal
|
|
file) then the behavior of the ROLLBACK command is undefined.
|
|
</p>
|
|
|
|
<h1 id="response_to_errors_within_a_transaction"><span>3. </span>Response To Errors Within A Transaction</h1>
|
|
|
|
<p> If certain kinds of errors occur within a transaction, the
|
|
transaction may or may not be rolled back automatically. The
|
|
errors that can cause an automatic rollback include:</p>
|
|
|
|
<ul>
|
|
<li> <a href="rescode.html#full">SQLITE_FULL</a>: database or disk full
|
|
</li><li> <a href="rescode.html#ioerr">SQLITE_IOERR</a>: disk I/O error
|
|
</li><li> <a href="rescode.html#busy">SQLITE_BUSY</a>: database in use by another process
|
|
</li><li> <a href="rescode.html#nomem">SQLITE_NOMEM</a>: out of memory
|
|
</li></ul>
|
|
|
|
<p>
|
|
For all of these errors, SQLite attempts to undo just the one statement
|
|
it was working on and leave changes from prior statements within the
|
|
same transaction intact and continue with the transaction. However,
|
|
depending on the statement being evaluated and the point at which the
|
|
error occurs, it might be necessary for SQLite to rollback and
|
|
cancel the entire transaction. An application can tell which
|
|
course of action SQLite took by using the
|
|
<a href="c3ref/get_autocommit.html">sqlite3_get_autocommit()</a> C-language interface.</p>
|
|
|
|
<p>It is recommended that applications respond to the errors
|
|
listed above by explicitly issuing a ROLLBACK command. If the
|
|
transaction has already been rolled back automatically
|
|
by the error response, then the ROLLBACK command will fail with an
|
|
error, but no harm is caused by this.</p>
|
|
|
|
<p>Future versions of SQLite may extend the list of errors which
|
|
might cause automatic transaction rollback. Future versions of
|
|
SQLite might change the error response. In particular, we may
|
|
choose to simplify the interface in future versions of SQLite by
|
|
causing the errors above to force an unconditional rollback.</p>
|
|
|