Expand DBI documentation (#190)

R/DBI-custom.R

@@ -17,6 +17,7 @@
 #'   bound to a connection. Instead use [poolWithTransaction()].
 #'
 #' * [DBI::dbDisconnect()] can't work because pool handles disconnection.
+#'   Use [poolClose()] instead.
 #'
 #' * [DBI::dbGetInfo()] returns information about the pool, not the database
 #'   connection.

R/DBI-wrap.R

@@ -4,9 +4,9 @@
 #' These pool method for DBI generics methods check out a connection
 #' (with [poolCheckout()]), re-call the generic, then return the connection
 #' to the pool (with [poolReturn()]).
+#' See [DBI-custom] for DBI methods that do not work with pool objects.
 #'
 #' @name DBI-wrap
-#' @keywords internal
 #' @examples
 #' mtcars1 <- mtcars[ c(1:16), ] # first half of the mtcars dataset
 #' mtcars2 <- mtcars[-c(1:16), ] # second half of the mtcars dataset
@@ -77,113 +77,142 @@ DBI_wrap <- function(fun_name) {
 }
 
 #' @export
+#' @inheritParams DBI::dbDataType
 #' @rdname DBI-wrap
 setMethod("dbDataType", "Pool", DBI_wrap("dbDataType"))
 
 #' @export
+#' @inheritParams DBI::dbGetQuery
 #' @rdname DBI-wrap
 setMethod("dbGetQuery", "Pool", DBI_wrap("dbGetQuery"))
 
 #' @export
+#' @inheritParams DBI::dbExecute
 #' @rdname DBI-wrap
 setMethod("dbExecute", "Pool", DBI_wrap("dbExecute"))
 
 #' @export
+#' @inheritParams DBI::dbListFields
 #' @rdname DBI-wrap
 setMethod("dbListFields", "Pool", DBI_wrap("dbListFields"))
 
 #' @export
+#' @inheritParams DBI::dbListTables
 #' @rdname DBI-wrap
 setMethod("dbListTables", "Pool", DBI_wrap("dbListTables"))
 
 #' @export
+#' @inheritParams DBI::dbListObjects
 #' @rdname DBI-wrap
 setMethod("dbListObjects", "Pool", DBI_wrap("dbListObjects"))
 
 #' @export
+#' @inheritParams DBI::dbReadTable
 #' @rdname DBI-wrap
 setMethod("dbReadTable", "Pool", DBI_wrap("dbReadTable"))
 
 #' @export
+#' @inheritParams DBI::dbWriteTable
 #' @rdname DBI-wrap
 setMethod("dbWriteTable", "Pool", DBI_wrap("dbWriteTable"))
 
 #' @export
+#' @inheritParams DBI::dbCreateTable
 #' @rdname DBI-wrap
 setMethod("dbCreateTable", "Pool", DBI_wrap("dbCreateTable"))
 
 #' @export
+#' @inheritParams DBI::dbAppendTable
 #' @rdname DBI-wrap
 setMethod("dbAppendTable", "Pool", DBI_wrap("dbAppendTable"))
 
 #' @export
+#' @inheritParams DBI::dbExistsTable
 #' @rdname DBI-wrap
 setMethod("dbExistsTable", "Pool", DBI_wrap("dbExistsTable"))
 
 #' @export
+#' @inheritParams DBI::dbRemoveTable
 #' @rdname DBI-wrap
 setMethod("dbRemoveTable", "Pool", DBI_wrap("dbRemoveTable"))
 
 #' @export
+#' @inheritParams DBI::dbIsReadOnly
 #' @rdname DBI-wrap
 setMethod("dbIsReadOnly", "Pool", DBI_wrap("dbIsReadOnly"))
 
 #' @export
+#' @inheritParams DBI::sqlData
 #' @rdname DBI-wrap
 setMethod("sqlData", "Pool", DBI_wrap("sqlData"))
 
 #' @export
+#' @inheritParams DBI::sqlCreateTable
 #' @rdname DBI-wrap
 setMethod("sqlCreateTable", "Pool", DBI_wrap("sqlCreateTable"))
 
 #' @export
+#' @inheritParams DBI::sqlAppendTable
 #' @rdname DBI-wrap
 setMethod("sqlAppendTable", "Pool", DBI_wrap("sqlAppendTable"))
 
 #' @export
+#' @inheritParams DBI::sqlInterpolate
+#' @param .dots A list of named arguments to interpolate.
 #' @rdname DBI-wrap
 setMethod("sqlInterpolate", "Pool", DBI_wrap("sqlInterpolate"))
 
 #' @export
+#' @inheritParams DBI::sqlParseVariables
 #' @rdname DBI-wrap
 setMethod("sqlParseVariables", "Pool", DBI_wrap("sqlParseVariables"))
 
 #' @export
+#' @inheritParams DBI::dbQuoteIdentifier
 #' @rdname DBI-wrap
 setMethod("dbQuoteIdentifier", "Pool", DBI_wrap("dbQuoteIdentifier"))
 
 #' @export
+#' @inheritParams DBI::dbUnquoteIdentifier
 #' @rdname DBI-wrap
 setMethod("dbUnquoteIdentifier", "Pool", DBI_wrap("dbUnquoteIdentifier"))
 
 #' @export
+#' @inheritParams DBI::dbQuoteLiteral
 #' @rdname DBI-wrap
 setMethod("dbQuoteLiteral", "Pool", DBI_wrap("dbQuoteLiteral"))
 
 #' @export
+#' @inheritParams DBI::dbQuoteString
 #' @rdname DBI-wrap
 setMethod("dbQuoteString", "Pool", DBI_wrap("dbQuoteString"))
 
 #' @export
+#' @inheritParams DBI::dbAppendTableArrow
 #' @rdname DBI-wrap
 setMethod("dbAppendTableArrow", "Pool", DBI_wrap("dbAppendTableArrow"))
 
 #' @export
+#' @inheritParams DBI::dbCreateTableArrow
 #' @rdname DBI-wrap
 setMethod("dbCreateTableArrow", "Pool", DBI_wrap("dbCreateTableArrow"))
 
 #' @export
+#' @inheritParams DBI::dbGetQueryArrow
 #' @rdname DBI-wrap
 setMethod("dbGetQueryArrow", "Pool", DBI_wrap("dbGetQueryArrow"))
 
 #' @export
+#' @inheritParams DBI::dbReadTableArrow
 #' @rdname DBI-wrap
 setMethod("dbReadTableArrow", "Pool", DBI_wrap("dbReadTableArrow"))
 
 #' @export
+#' @inheritParams DBI::dbSendQueryArrow
 #' @rdname DBI-wrap
 setMethod("dbSendQueryArrow", "Pool", DBI_wrap("dbSendQueryArrow"))
 
 #' @export
+#' @inheritParams DBI::dbWriteTableArrow
 #' @rdname DBI-wrap
 setMethod("dbWriteTableArrow", "Pool", DBI_wrap("dbWriteTableArrow"))

R/DBI.R

@@ -3,6 +3,18 @@
 #' `dbPool()` is a drop-in replacement for [DBI::dbConnect()] that
 #' provides a shared pool of connections that can automatically reconnect
 #' to the database if needed.
+#' See [DBI-wrap] for methods to use with pool objects,
+#' and [DBI-custom] for unsupported methods and the "pool" way of using them.
+#'
+#' A new connection is created transparently
+#'
+#' - if the pool is empty
+#' - if the currently checked out connection is invalid
+#'   (checked at most once every `validationInterval` seconds)
+#' - if the pool is not full and the connections are all in use
+#'
+#' Use [poolClose()] to close the pool and all connections in it.
+#' See [poolCraete()] for details on the internal workings of the pool.
 #'
 #' @param drv A [DBI Driver][DBI::DBIDriver-class], e.g. `RSQLite::SQLite()`,
 #'   `RPostgres::Postgres()`, `odbc::odbc()` etc.

R/pool-methods.R

@@ -82,7 +82,8 @@ setMethod("poolClose", "Pool", function(pool) {
 #' When pooling DBI database connections, you normally would not use
 #' `poolCheckout()`. Instead, for single-shot queries, treat the pool object
 #' itself as the DBI connection object and it will perform checkout/return for
-#' you. And for transactions, use [poolWithTransaction()].
+#' you. And for transactions, use [poolWithTransaction()]. See [dbPool()] for
+#' an example.
 #'
 #' @param pool The pool to get the object from.
 #' @export

_pkgdown.yml

@@ -20,6 +20,7 @@ reference:
 - title: Database functions
   contents:
   - dbPool
-  - 'DBI-custom'
+  - 'DBI-wrap'
   - poolWithTransaction
   - tbl.Pool
+  - 'DBI-custom'