transactions {DBI} | R Documentation |
A transaction encapsulates several SQL statements in an atomic unit.
It is initiated with dbBegin()
and either made persistent with dbCommit()
or undone with dbRollback()
.
In any case, the DBMS guarantees that either all or none of the statements
have a permanent effect.
This helps ensuring consistency of write operations to multiple tables.
dbBegin(conn, ...) dbCommit(conn, ...) dbRollback(conn, ...)
conn |
A DBIConnection object, as returned by
|
... |
Other parameters passed on to methods. |
Not all database engines implement transaction management, in which case these methods should not be implemented for the specific DBIConnection subclass.
dbBegin()
, dbCommit()
and dbRollback()
return TRUE
, invisibly.
The implementations are expected to raise an error in case of failure,
but this is not tested.
In any way, all generics throw an error with a closed
or invalid connection.
In addition, a call to dbCommit()
or dbRollback()
without a prior call to dbBegin()
raises an error.
Nested transactions are not supported by DBI,
an attempt to call dbBegin()
twice
yields an error.
Actual support for transactions may vary between backends.
A transaction is initiated by a call to dbBegin()
and committed by a call to dbCommit()
.
Data written in a transaction must persist after the transaction is committed.
For example, a table that is missing when the transaction is started
but is created
and populated during the transaction
must exist and contain the data added there
both during
and after the transaction,
and also in a new connection.
A transaction
can also be aborted with dbRollback()
.
All data written in such a transaction must be removed after the
transaction is rolled back.
For example, a table that is missing when the transaction is started
but is created during the transaction
must not exist anymore after the rollback.
Disconnection from a connection with an open transaction effectively rolls back the transaction. All data written in such a transaction must be removed after the transaction is rolled back.
The behavior is not specified if other arguments are passed to these
functions. In particular, RSQLite issues named transactions
with support for nesting
if the name
argument is set.
The transaction isolation level is not specified by DBI.
Self-contained transactions: dbWithTransaction()
con <- dbConnect(RSQLite::SQLite(), ":memory:") dbWriteTable(con, "cash", data.frame(amount = 100)) dbWriteTable(con, "account", data.frame(amount = 2000)) # All operations are carried out as logical unit: dbBegin(con) withdrawal <- 300 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) dbCommit(con) dbReadTable(con, "cash") dbReadTable(con, "account") # Rolling back after detecting negative value on account: dbBegin(con) withdrawal <- 5000 dbExecute(con, "UPDATE cash SET amount = amount + ?", list(withdrawal)) dbExecute(con, "UPDATE account SET amount = amount - ?", list(withdrawal)) if (dbReadTable(con, "account")$amount >= 0) { dbCommit(con) } else { dbRollback(con) } dbReadTable(con, "cash") dbReadTable(con, "account") dbDisconnect(con)