Merge pull request #110 from bborgesr/dbWithTransaction

- New `dbWithTransaction()` that calls `dbBegin()` and `dbCommit()`, and `dbRollback()` on failure (#110, @bborgesr).

NAMESPACE

@@ -38,6 +38,7 @@ export(dbRollback)
 export(dbSendQuery)
 export(dbSetDataMappings)
 export(dbUnloadDriver)
+export(dbWithTransaction)
 export(dbWriteTable)
 export(fetch)
 export(isSQLKeyword)
@@ -65,6 +66,7 @@ exportMethods(dbDataType)
 exportMethods(dbExecute)
 exportMethods(dbGetQuery)
 exportMethods(dbQuoteIdentifier)
+exportMethods(dbWithTransaction)
 exportMethods(show)
 exportMethods(sqlAppendTable)
 exportMethods(sqlCreateTable)

NEWS.md

@@ -1,9 +1,8 @@
 # DBI 0.4-2 (2016-06-08)
 
-- Remove redundant declaration of transaction methods (#110, @@bborgesr).
+- Remove redundant declaration of transaction methods (#110, @bborgesr).
 - New `dbExecute()`, forwards to `dbSendQuery()` by default (#109, @bborgesr).
 
-
 # DBI 0.4-1 (2016-05-07)
 
 - The default `show()` implementations silently ignore all errors.  Some DBI drivers (e.g., RPostgreSQL) might fail to implement `dbIsValid()` or the other methods used.

R/transactions.R

@@ -44,3 +44,75 @@ setGeneric("dbRollback",
   def = function(conn, ...) standardGeneric("dbRollback"),
   valueClass = "logical"
 )
+
+#' Self-contained SQL transactions.
+#'
+#' Given that \code{\link{transactions}} are implemented, then this function
+#' allows you pass in code that is treated as a transaction. The advantage is
+#' that you don't have to remember to do \code{dbBegin} and \code{dbCommit} or
+#' \code{dbRollback} -- that is all taken care of.
+#'
+#' @section Side Effects:
+#' The transaction in \code{code} on the connection \code{conn} is committed
+#' or rolled back. The \code{code} chunk may also also modify the local R
+#' environment.
+#'
+#' @param conn A \code{\linkS4class{DBIConnection}} object, as produced by
+#'   \code{\link{dbConnect}}.
+#' @param code An arbitrary block of R code
+#'
+#' @return The result of the evaluation of \code{code}
+#' @aliases dbWithTransaction,DBIConnection-method
+#' @export
+#' @examples
+#' con <- dbConnect(RSQLite::SQLite(), ":memory:")
+#' dbWriteTable(con, "cars", head(cars, 3))
+#' dbReadTable(con, "cars")   # there's 3 rows!
+#' ## successful transaction
+#' dbWithTransaction(con, {
+#'   dbExecute(con, "INSERT INTO cars (speed, dist) VALUES (1, 1);")
+#'   dbExecute(con, "INSERT INTO cars (speed, dist) VALUES (2, 2);")
+#'   dbExecute(con, "INSERT INTO cars (speed, dist) VALUES (3, 3);")
+#' })
+#' dbReadTable(con, "cars")   # there's now 6 rows!
+#'
+#' \dontrun{
+#' ## unsuccessful transaction -- note the missing comma
+#' dbWithTransaction(con,{
+#'   dbExecute(con, "INSERT INTO cars (speed, dist) VALUES (1, 1);")
+#'   dbExecute(con, "INSERT INTO cars (speed dist) VALUES (2, 2);")
+#'   dbExecute(con, "INSERT INTO cars (speed, dist) VALUES (3, 3);")
+#' })
+#' dbReadTable(con, "cars")   # nothing was changed
+#' }
+#' dbDisconnect(con)
+setGeneric("dbWithTransaction",
+  def = function(conn, code) standardGeneric("dbWithTransaction")
+)
+
+#' @export
+setMethod("dbWithTransaction", "DBIConnection", function(conn, code) {
+  ## check if each operation is successful
+  call <- dbBegin(conn)
+  if (identical(call, FALSE)) {
+    stop("Failed to begin transaction", call. = FALSE)
+  }
+  tryCatch({
+    res <- force(code)
+    call <- dbCommit(conn)
+    if (identical(call, FALSE)) {
+      stop("Failed to commit transaction", call. = FALSE)
+    }
+    res
+  },
+  error = function(e) {
+    call <- dbRollback(conn)
+    if (identical(call, FALSE)) {
+      stop(paste("Failed to rollback transaction.",
+                 "Tried to roll back because an error",
+                 "occurred:", conditionMessage(e)),
+           call. = FALSE)
+    }
+    stop(e)
+  })
+})