From 3cd4af3a3f93ee0be4818c77e80517756af6d20e Mon Sep 17 00:00:00 2001
From: Joe Cheng <joe@posit.co>
Date: Wed, 21 Aug 2024 09:53:57 -0700
Subject: [PATCH] Recommend against poolCheckout for DBI

---
 R/pool-methods.R    | 7 +++++++
 man/poolCheckout.Rd | 7 +++++++
 2 files changed, 14 insertions(+)

diff --git a/R/pool-methods.R b/R/pool-methods.R
index bcc34a5..94ebc6c 100644
--- a/R/pool-methods.R
+++ b/R/pool-methods.R
@@ -78,11 +78,18 @@ setMethod("poolClose", "Pool", function(pool) {
 #' Note that validation is only performed when the object is checked out,
 #' so you generally want to keep the checked out around for as little time as
 #' possible.
+#' 
+#' 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()].
 #'
 #' @param pool The pool to get the object from.
 #' @export
 #' @examples
 #' pool <- dbPool(RSQLite::SQLite())
+#' # For illustration only. You normally would not explicitly use
+#' # poolCheckout with a DBI connection pool (see Description).
 #' con <- poolCheckout(pool)
 #' con
 #' poolReturn(con)
diff --git a/man/poolCheckout.Rd b/man/poolCheckout.Rd
index 0cfb84c..e936101 100644
--- a/man/poolCheckout.Rd
+++ b/man/poolCheckout.Rd
@@ -39,9 +39,16 @@ the function exits
 Note that validation is only performed when the object is checked out,
 so you generally want to keep the checked out around for as little time as
 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()}}.
 }
 \examples{
 pool <- dbPool(RSQLite::SQLite())
+# For illustration only. You normally would not explicitly use
+# poolCheckout with a DBI connection pool (see Description).
 con <- poolCheckout(pool)
 con
 poolReturn(con)