Merge branch 'r-0.7-14' into production

API

@@ -3,7 +3,7 @@
 ## Exported functions
 
 ANSI()
-SQL(x)
+SQL(x, ..., names = NULL)
 SQLKeywords(dbObj, ...)
 dbBegin(conn, ...)
 dbBind(res, params, ...)

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: DBI
-Version: 0.7-13
-Date: 2017-11-27
+Version: 0.7-14
+Date: 2018-01-27
 Title: R Database Interface
 Description: A database interface definition for communication
     between R and relational database management systems.  All
@@ -43,6 +43,7 @@ Collate:
     'hidden.R'
     'interpolate.R'
     'quote.R'
+    'rd.R'
     'rownames.R'
     'table-create.R'
     'table-insert.R'

NEWS.md

@@ -1,3 +1,13 @@
+## DBI 0.7-14 (2018-01-27)
+
+- The `SQL()` function gains a `names` argument which can be used to assign names to SQL strings.
+- `dbListResults()` is deprecated by documentation (#58).
+- `dbGetException()` is soft-deprecated by documentation (#51).
+- Help pages for generics now contain a dynamic list of methods implemented by DBI backends (#162).
+- `sqlInterpolate()` now supports both named and positional variables (#216, @hannesmuehleisen).
+- Specialized methods for `dbQuoteString()` and `dbQuoteIdentifier()` are available again, for compatibility with clients that use `getMethod()` to access them (#218).
+
+
 ## DBI 0.7-13 (2017-11-27)
 
 - The deprecated `print.list.pairs()` has been removed.

R/DBConnection.R

@@ -34,7 +34,8 @@ setMethod("show", "DBIConnection", function(object) {
   # RPostgreSQL)
   tryCatch(
     show_connection(object),
-    error = function(e) NULL)
+    error = function(e) NULL
+  )
   invisible(NULL)
 })
 
@@ -50,6 +51,9 @@ show_connection <- function(object) {
 #' This closes the connection, discards all pending work, and frees
 #' resources (e.g., memory, sockets).
 #'
+#' @template methods
+#' @templateVar method_name dbDisconnect
+#'
 #' @inherit DBItest::spec_connection_disconnect return
 #' @inheritSection DBItest::spec_connection_disconnect Specification
 #'
@@ -83,6 +87,10 @@ setGeneric("dbDisconnect",
 #' and transfer them piecemeal to R, others may transfer all the data to the
 #' client -- but not necessarily to the memory that R manages. See individual
 #' drivers' `dbSendQuery()` documentation for details.
+#'
+#' @template methods
+#' @templateVar method_name dbSendQuery
+#'
 #' @inherit DBItest::spec_result_send_query return
 #' @inheritSection DBItest::spec_result_send_query Specification
 #'
@@ -120,6 +128,9 @@ setGeneric("dbSendQuery",
 #' forwards to [dbSendQuery()], to support backends that only
 #' implement the latter.
 #'
+#' @template methods
+#' @templateVar method_name dbSendStatement
+#'
 #' @inherit DBItest::spec_result_send_statement return
 #' @inheritSection DBItest::spec_result_send_statement Specification
 #'
@@ -168,6 +179,9 @@ setMethod(
 #' reasons.  However, callers are strongly advised to use
 #' [dbExecute()] for data manipulation statements.
 #'
+#' @template methods
+#' @templateVar method_name dbGetQuery
+#'
 #' @inherit DBItest::spec_result_get_query return
 #' @inheritSection DBItest::spec_result_get_query Specification
 #'
@@ -213,6 +227,9 @@ setMethod("dbGetQuery", signature("DBIConnection", "character"),
 #' [dbSendStatement()], then [dbGetRowsAffected()], ensuring that
 #' the result is always free-d by [dbClearResult()].
 #'
+#' @template methods
+#' @templateVar method_name dbExecute
+#'
 #' @section Implementation notes:
 #' Subclasses should override this method only if they provide some sort of
 #' performance optimization.
@@ -251,6 +268,9 @@ setMethod(
 
 #' Get DBMS exceptions
 #'
+#' DEPRECATED. Backends should use R's condition system to signal errors and
+#' warnings.
+#'
 #' @inheritParams dbGetQuery
 #' @family DBIConnection generics
 #' @return a list with elements `errorNum` (an integer error number) and
@@ -263,7 +283,9 @@ setGeneric("dbGetException",
 
 #' A list of all pending results
 #'
-#' List of [DBIResult-class] objects currently active on the connection.
+#' DEPRECATED. DBI currenty supports only one open result set per connection,
+#' you need to keep track of the result sets you open if you need this
+#' functionality.
 #'
 #' @inheritParams dbGetQuery
 #' @family DBIConnection generics
@@ -296,10 +318,16 @@ setGeneric("dbListFields",
 
 #' @rdname hidden_aliases
 #' @export
-setMethod("dbListFields", c("DBIConnection", "character"),
+setMethod("dbListFields", signature("DBIConnection", "character"),
   function(conn, name, ...) {
-    rs <- dbSendQuery(conn, paste("SELECT * FROM ",
-                                  dbQuoteIdentifier(conn, name), "LIMIT 0"))
+    rs <- dbSendQuery(
+      conn,
+      paste(
+        "SELECT * FROM ",
+        dbQuoteIdentifier(conn, name),
+        "LIMIT 0"
+      )
+    )
     on.exit(dbClearResult(rs))
 
     names(dbFetch(rs, n = 0, row.names = FALSE))
@@ -312,6 +340,9 @@ setMethod("dbListFields", c("DBIConnection", "character"),
 #' connection.
 #' This should, where possible, include temporary tables, and views.
 #'
+#' @template methods
+#' @templateVar method_name dbListTables
+#'
 #' @inherit DBItest::spec_sql_list_tables return
 #' @inheritSection DBItest::spec_sql_list_tables Additional arguments
 #'
@@ -337,6 +368,9 @@ setGeneric("dbListTables",
 #' a column to row names and converting the column names to valid
 #' R identifiers.
 #'
+#' @template methods
+#' @templateVar method_name dbReadTable
+#'
 #' @inherit DBItest::spec_sql_read_table return
 #' @inheritSection DBItest::spec_sql_read_table Additional arguments
 #' @inheritSection DBItest::spec_sql_read_table Specification
@@ -388,6 +422,9 @@ setMethod("dbReadTable", c("DBIConnection", "character"),
 #' Writes, overwrites or appends a data frame to a database table, optionally
 #' converting row names to a column and specifying SQL data types for fields.
 #'
+#' @template methods
+#' @templateVar method_name dbWriteTable
+#'
 #' @inherit DBItest::spec_sql_write_table return
 #' @inheritSection DBItest::spec_sql_write_table Additional arguments
 #' @inheritSection DBItest::spec_sql_write_table Specification
@@ -422,6 +459,9 @@ setGeneric("dbWriteTable",
 #'
 #' Returns if a table given by name exists in the database.
 #'
+#' @template methods
+#' @templateVar method_name dbExistsTable
+#'
 #' @inherit DBItest::spec_sql_exists_table return
 #' @inheritSection DBItest::spec_sql_exists_table Additional arguments
 #' @inheritSection DBItest::spec_sql_exists_table Specification
@@ -448,6 +488,9 @@ setGeneric("dbExistsTable",
 #' Remove a remote table (e.g., created by [dbWriteTable()])
 #' from the database.
 #'
+#' @template methods
+#' @templateVar method_name dbRemoveTable
+#'
 #' @inherit DBItest::spec_sql_remove_table return
 #' @inheritSection DBItest::spec_sql_remove_table Specification
 #'

R/DBDriver.R

@@ -55,10 +55,11 @@ setClass("DBIDriver", contains = c("DBIObject", "VIRTUAL"))
 #' @export
 setGeneric("dbDriver",
   def = function(drvName, ...) standardGeneric("dbDriver"),
-  valueClass = "DBIDriver")
+  valueClass = "DBIDriver"
+)
 
 #' @rdname hidden_aliases
-setMethod("dbDriver", "character",
+setMethod("dbDriver", signature("character"),
   definition = function(drvName, ...) {
     findDriver(drvName)(...)
   }
@@ -72,7 +73,8 @@ setMethod("show", "DBIDriver", function(object) {
     # to protect drivers that fail to implement the required methods (e.g.,
     # RPostgreSQL)
     show_driver(object),
-    error = function(e) NULL)
+    error = function(e) NULL
+  )
   invisible(NULL)
 })
 
@@ -99,11 +101,13 @@ findDriver <- function(drvName) {
   }
 
   # Can't find it:
-  stop("Couldn't find driver ", drvName, ". Looked in:\n",
+  stop(
+    "Couldn't find driver ", drvName, ". Looked in:\n",
     "* global namespace\n",
     "* in package called ", drvName, "\n",
     "* in package called ", pkgName,
-    call. = FALSE)
+    call. = FALSE
+  )
 }
 
 get2 <- function(x, env) {
@@ -134,6 +138,9 @@ setGeneric("dbUnloadDriver",
 #' The authentication mechanism is left unspecified, so check the
 #' documentation of individual drivers for details.
 #'
+#' @template methods
+#' @templateVar method_name dbConnect
+#'
 #' @inherit DBItest::spec_driver_connect return
 #' @inheritSection DBItest::spec_driver_connect Specification
 #'
@@ -196,6 +203,9 @@ setGeneric("dbListConnections",
 #' Notice that many DBMS do not follow IEEE arithmetic, so there are potential
 #' problems with under/overflows and loss of precision.
 #'
+#' @template methods
+#' @templateVar method_name dbDataType
+#'
 #' @inherit DBItest::spec_driver_data_type return
 #' @inheritSection DBItest::spec_driver_data_type Specification
 #' @inheritSection DBItest::spec_result_create_table_with_data_type Specification

R/DBObject.R

@@ -74,14 +74,17 @@ setClass("DBIObject", "VIRTUAL")
 #' @return a named list
 #' @export
 setGeneric("dbGetInfo",
-   def = function(dbObj, ...) standardGeneric("dbGetInfo")
+  def = function(dbObj, ...) standardGeneric("dbGetInfo")
 )
 
 #' Is this DBMS object still valid?
 #'
 #' This generic tests whether a database object is still valid (i.e. it hasn't
 #' been disconnected or cleared).
 #'
+#' @template methods
+#' @templateVar method_name dbIsValid
+#'
 #' @inherit DBItest::spec_meta_is_valid return
 #'
 #' @inheritParams dbGetInfo
@@ -105,7 +108,8 @@ setGeneric("dbGetInfo",
 #' dbIsValid(con)
 setGeneric("dbIsValid",
   def = function(dbObj, ...) standardGeneric("dbIsValid"),
-  valueClass = "logical")
+  valueClass = "logical"
+)
 
 setGeneric("summary")
 setMethod("summary", "DBIObject", function(object, ...) {

R/DBResult.R

@@ -29,13 +29,14 @@ setMethod("show", "DBIResult", function(object) {
   # RPostgreSQL)
   tryCatch(
     show_result(object),
-    error = function(e) NULL)
+    error = function(e) NULL
+  )
   invisible(NULL)
 })
 
 show_result <- function(object) {
   cat("<", is(object)[1], ">\n", sep = "")
-  if(!dbIsValid(object)){
+  if (!dbIsValid(object)) {
     cat("EXPIRED\n")
   } else {
     cat("  SQL  ", dbGetStatement(object), "\n", sep = "")
@@ -56,6 +57,9 @@ show_result <- function(object) {
 #' implementation for `dbFetch()` calls `fetch()` so that it is compatible with
 #' existing code. Modern backends should implement for `dbFetch()` only.
 #'
+#' @template methods
+#' @templateVar method_name dbFetch
+#'
 #' @inherit DBItest::spec_result_fetch return
 #' @inheritSection DBItest::spec_result_fetch Specification
 #' @inheritSection DBItest::spec_result_roundtrip Specification
@@ -114,6 +118,9 @@ setGeneric("fetch",
 #' cases (e.g., very large result sets) this can be a critical step to avoid
 #' exhausting resources (memory, file descriptors, etc.)
 #'
+#' @template methods
+#' @templateVar method_name dbClearResult
+#'
 #' @inherit DBItest::spec_result_clear_result return
 #' @inheritSection DBItest::spec_result_clear_result Specification
 #'
@@ -167,6 +174,9 @@ setGeneric("dbColumnInfo",
 #' Returns the statement that was passed to [dbSendQuery()]
 #' or [dbSendStatement()].
 #'
+#' @template methods
+#' @templateVar method_name dbGetStatement
+#'
 #' @inherit DBItest::spec_meta_get_statement return
 #'
 #' @inheritParams dbClearResult
@@ -193,6 +203,9 @@ setGeneric("dbGetStatement",
 #' A `SELECT` query is completed if all rows have been fetched.
 #' A data manipulation statement is always completed.
 #'
+#' @template methods
+#' @templateVar method_name dbHasCompleted
+#'
 #' @inherit DBItest::spec_meta_has_completed return
 #' @inheritSection DBItest::spec_meta_has_completed Specification
 #'
@@ -224,6 +237,9 @@ setGeneric("dbHasCompleted",
 #' This method returns the number of rows that were added, deleted, or updated
 #' by a data manipulation statement.
 #'
+#' @template methods
+#' @templateVar method_name dbGetRowsAffected
+#'
 #' @inherit DBItest::spec_meta_get_rows_affected return
 #'
 #' @inheritParams dbClearResult
@@ -250,6 +266,9 @@ setGeneric("dbGetRowsAffected",
 #' Returns the total number of rows actually fetched with calls to [dbFetch()]
 #' for this result set.
 #'
+#' @template methods
+#' @templateVar method_name dbGetRowCount
+#'
 #' @inherit DBItest::spec_meta_get_row_count return
 #'
 #' @inheritParams dbClearResult
@@ -327,6 +346,9 @@ setMethod("dbGetInfo", "DBIResult", function(dbObj, ...) {
 #' - `$1` (positional matching by index) in \pkg{RPostgres} and \pkg{RSQLite}
 #' - `:name` and `$name` (named matching) in \pkg{RSQLite}
 #'
+#' @template methods
+#' @templateVar method_name dbBind
+#'
 #' @inherit DBItest::spec_meta_bind return
 #' @inheritSection DBItest::spec_meta_bind Specification
 #'