1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
|
#' Execute a data manipulation statement on a given database connection
#'
#' The `dbSendStatement()` method only submits and synchronously executes the
#' SQL data manipulation statement (e.g., `UPDATE`, `DELETE`,
#' `INSERT INTO`, `DROP TABLE`, ...) to the database engine. To query
#' the number of affected rows, call [dbGetRowsAffected()] on the
#' returned result object. You must also call [dbClearResult()] after
#' that. For interactive use, you should almost always prefer
#' [dbExecute()].
#'
#' [dbSendStatement()] comes with a default implementation that simply
#' forwards to [dbSendQuery()], to support backends that only
#' implement the latter.
#'
#' @inheritSection dbBind The command execution flow
#'
#' @template methods
#' @templateVar method_name dbSendStatement
#'
#' @inherit DBItest::spec_result_send_statement return
#' @inheritSection DBItest::spec_result_send_statement Failure modes
#' @inheritSection DBItest::spec_result_send_statement Additional arguments
#' @inheritSection DBItest::spec_result_send_statement Specification
#' @inheritSection DBItest::spec_result_send_statement Specification for the `immediate` argument
#'
#' @inheritParams dbGetQuery
#' @param statement a character string containing SQL.
#'
#' @family DBIConnection generics
#' @family command execution generics
#'
#' @seealso For queries: [dbSendQuery()] and [dbGetQuery()].
#' @examplesIf requireNamespace("RSQLite", quietly = TRUE)
#' con <- dbConnect(RSQLite::SQLite(), ":memory:")
#'
#' dbWriteTable(con, "cars", head(cars, 3))
#'
#' rs <- dbSendStatement(
#' con,
#' "INSERT INTO cars (speed, dist) VALUES (1, 1), (2, 2), (3, 3)"
#' )
#' dbHasCompleted(rs)
#' dbGetRowsAffected(rs)
#' dbClearResult(rs)
#' dbReadTable(con, "cars") # there are now 6 rows
#'
#' # Pass one set of values directly using the param argument:
#' rs <- dbSendStatement(
#' con,
#' "INSERT INTO cars (speed, dist) VALUES (?, ?)",
#' params = list(4L, 5L)
#' )
#' dbClearResult(rs)
#'
#' # Pass multiple sets of values using dbBind():
#' rs <- dbSendStatement(
#' con,
#' "INSERT INTO cars (speed, dist) VALUES (?, ?)"
#' )
#' dbBind(rs, list(5:6, 6:7))
#' dbBind(rs, list(7L, 8L))
#' dbClearResult(rs)
#' dbReadTable(con, "cars") # there are now 10 rows
#'
#' dbDisconnect(con)
#' @export
setGeneric(
"dbSendStatement",
def = function(conn, statement, ...) standardGeneric("dbSendStatement"),
valueClass = "DBIResult"
)
|
