docs: Expand DBI documentation

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

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'