From 2c5bd6c90ac97f990b30be0be31577117d019441 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Kirill=20M=C3=BCller?= Date: Wed, 21 Aug 2024 20:54:13 +0200 Subject: [PATCH] docs: Expand DBI documentation --- R/DBI-custom.R | 1 + R/DBI-wrap.R | 2 +- R/DBI.R | 12 ++++++++++++ R/pool-methods.R | 3 ++- _pkgdown.yml | 3 ++- man/DBI-custom.Rd | 1 + man/DBI-wrap.Rd | 2 +- man/dbPool.Rd | 13 +++++++++++++ man/poolCheckout.Rd | 3 ++- 9 files changed, 35 insertions(+), 5 deletions(-) diff --git a/R/DBI-custom.R b/R/DBI-custom.R index 8ae936b..aacf90a 100644 --- a/R/DBI-custom.R +++ b/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. diff --git a/R/DBI-wrap.R b/R/DBI-wrap.R index 9f859d5..916517d 100644 --- a/R/DBI-wrap.R +++ b/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 diff --git a/R/DBI.R b/R/DBI.R index 543bdc6..9020f4b 100644 --- a/R/DBI.R +++ b/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. diff --git a/R/pool-methods.R b/R/pool-methods.R index 94ebc6c..2f091ef 100644 --- a/R/pool-methods.R +++ b/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 diff --git a/_pkgdown.yml b/_pkgdown.yml index a0d60b8..1e1793a 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -20,6 +20,7 @@ reference: - title: Database functions contents: - dbPool - - 'DBI-custom' + - 'DBI-wrap' - poolWithTransaction - tbl.Pool + - 'DBI-custom' diff --git a/man/DBI-custom.Rd b/man/DBI-custom.Rd index 43c386f..b314d55 100644 --- a/man/DBI-custom.Rd +++ b/man/DBI-custom.Rd @@ -51,6 +51,7 @@ Instead use \code{\link[DBI:dbGetQuery]{DBI::dbGetQuery()}}, \code{\link[DBI:dbE \code{\link[DBI:dbWithTransaction]{DBI::dbWithTransaction()}} can't work with pool because transactions are bound to a connection. Instead use \code{\link[=poolWithTransaction]{poolWithTransaction()}}. \item \code{\link[DBI:dbDisconnect]{DBI::dbDisconnect()}} can't work because pool handles disconnection. +Use \code{\link[=poolClose]{poolClose()}} instead. \item \code{\link[DBI:dbGetInfo]{DBI::dbGetInfo()}} returns information about the pool, not the database connection. \item \code{\link[DBI:dbIsValid]{DBI::dbIsValid()}} returns whether or not the entire pool is valid (i.e. diff --git a/man/DBI-wrap.Rd b/man/DBI-wrap.Rd index 2f0d166..5c4c0cc 100644 --- a/man/DBI-wrap.Rd +++ b/man/DBI-wrap.Rd @@ -92,6 +92,7 @@ These pool method for DBI generics methods check out a connection (with \code{\link[=poolCheckout]{poolCheckout()}}), re-call the generic, then return the connection to the pool (with \code{\link[=poolReturn]{poolReturn()}}). +See \link{DBI-custom} for DBI methods that do not work with pool objects. } \examples{ mtcars1 <- mtcars[ c(1:16), ] # first half of the mtcars dataset @@ -137,4 +138,3 @@ dbListTables(pool) poolClose(pool) } -\keyword{internal} diff --git a/man/dbPool.Rd b/man/dbPool.Rd index 7828ad7..aeb8b39 100644 --- a/man/dbPool.Rd +++ b/man/dbPool.Rd @@ -47,6 +47,19 @@ options, but these don't work for all databases.} \code{dbPool()} is a drop-in replacement for \code{\link[DBI:dbConnect]{DBI::dbConnect()}} that provides a shared pool of connections that can automatically reconnect to the database if needed. +See \link{DBI-wrap} for methods to use with pool objects, +and \link{DBI-custom} for unsupported methods and the "pool" way of using them. +} +\details{ +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. } \examples{ # You use a dbPool in the same way as a standard DBI connection diff --git a/man/poolCheckout.Rd b/man/poolCheckout.Rd index e936101..ee4c7f2 100644 --- a/man/poolCheckout.Rd +++ b/man/poolCheckout.Rd @@ -43,7 +43,8 @@ possible. When pooling DBI database connections, you normally would not use \code{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 \code{\link[=poolWithTransaction]{poolWithTransaction()}}. +you. And for transactions, use \code{\link[=poolWithTransaction]{poolWithTransaction()}}. See \code{\link[=dbPool]{dbPool()}} for +an example. } \examples{ pool <- dbPool(RSQLite::SQLite())