Begin stmt
No changes can be made to the database except within a transaction. Any command that changes the database (basically, any SQL command other than
SELECT) will automatically start a transaction if one is not already in effect. Automatically started transactions are committed when the last query finishes.
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
ON CONFLICT clause for additional information about the ROLLBACK conflict resolution algorithm.
END TRANSACTION is an alias for COMMIT.
Transactions created using BEGIN...COMMIT do not nest. For nested transactions, use the
SAVEPOINT and
RELEASE commands. The "TO SAVEPOINT
name" clause of the ROLLBACK command shown in the syntax diagram above is only applicable to
SAVEPOINT transactions. An attempt to invoke the BEGIN command within a transaction will fail with an error, regardless of whether the transaction was started by
SAVEPOINT or a prior BEGIN. The COMMIT command and the ROLLBACK command without the TO clause work the same on
SAVEPOINT transactions as they do with transactions started by BEGIN.
Transactions can be deferred, immediate, or exclusive. The default transaction behavior is deferred. Deferred means that no locks are acquired on the database until the database is first accessed. Thus with a deferred transaction, the BEGIN statement itself does nothing to the filesystem. Locks are not acquired until the first read or write operation. The first read operation against a database creates a
SHARED lock and the first write operation creates a
RESERVED lock. Because the acquisition of locks is deferred until they are needed, it is possible that another thread or process could create a separate transaction and write to the database after the BEGIN on the current thread has executed. If the transaction is immediate, then
RESERVED locks are acquired on all databases as soon as the BEGIN command is executed, without waiting for the database to be used. After a BEGIN IMMEDIATE, no other
database connection will be able to write to the database or do a BEGIN IMMEDIATE or BEGIN EXCLUSIVE. Other processes can continue to read from the database, however. An exclusive transaction causes
EXCLUSIVE locks to be acquired on all databases. After a BEGIN EXCLUSIVE, no other
database connectionexcept for
read_uncommitted connections will be able to read the database and no other connection without exception will be able to write the database until the transaction is complete.
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 prepared statement is
reset or
finalized. An open
sqlite3_blob used for incremental BLOB I/O counts as an unfinished statement. The
sqlite3_blobfinishes when it is
closed.
The explicit COMMIT command runs immediately, even if there are pending
SELECT statements. However, if there are pending write operations, the COMMIT command will fail with an error code
SQLITE_BUSY.
An attempt to execute COMMIT might also result in an
SQLITE_BUSY return code if an another thread or process has a
shared lock on the database that prevented the database from being updated. 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.
In very old versions of SQLite (before version 3.7.11 - 2012-03-20) the ROLLBACK will fail with an error code
SQLITE_BUSY 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
SQLITE_ABORT or
SQLITE_ABORT_ROLLBACK 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.
Example of an IMMEDIATE transaction:
- BEGIN IMMEDIATE TRANSACTION
- SELECT
- UPDATE
- SELECT
- UPDATE
- INSERT
- SELECT
- COMMIT
Here the reserved lock is obtained as soon as the BEGIN statement executes.
For the DEFERRED transaction:
- BEGIN DEFERRED TRANSACTION
- SELECT
- UPDATE
- SELECT
- UPDATE
- INSERT
- SELECT
- COMMIT
Here the shared lock is obtained after the begin statement till the update statement. The reserved lock is obtained when the update statement executes.