Document package connection lifetime

[LeonidasZhak]

Fixes #532.

This adds a short dbDisconnect() documentation section for package-level connection reuse. It keeps the guidance conservative:

• consider delegating connection lifetime management to the pool package
• if a package manages a long-lived connection itself, keep the connection object reachable until any finalizer runs
• guard finalizer disconnects with dbIsValid()

Checks:

• git diff --check
• R CMD build --no-build-vignettes .
• _R_CHECK_FORCE_SUGGESTS_=false R CMD check --no-manual --ignore-vignettes --no-build-vignettes --no-tests DBI_1.3.0.9010.tar.gz

[github-actions]

Formatting suggestions available

A patch file with formatting suggestions has been generated. You can apply it using one of these methods:

Method 1: Apply via gh CLI

# Download and apply the patch directly
gh run download 27011862185 --repo r-dbi/DBI --name changes-patch && patch -p1 < changes.patch && rm changes.patch

Repo owners can also apply the patch automatically. Click the button to jump to the comment box, then post:

/apply-patch

Method 2: View the patch

Click to see the patch contents

diff --git a/man/dbDisconnect.Rd b/man/dbDisconnect.Rd
index 9bbc389..b4f3377 100644
--- a/man/dbDisconnect.Rd
+++ b/man/dbDisconnect.Rd
@@ -21,6 +21,15 @@ resources (e.g., memory, sockets).
 
 \Sexpr[results=rd,stage=render]{DBI:::methods_as_rd("dbDisconnect")}
 }
+\section{Connection lifetime in packages}{
+
+For package-level connection reuse, consider delegating connection lifetime
+management to the pool package. If a package manages a long-lived connection
+itself, any finalizer that calls \code{dbDisconnect()} should keep the connection
+object reachable until the finalizer runs, and should check \code{\link[=dbIsValid]{dbIsValid()}}
+before disconnecting.
+}
+
 \section{Failure modes}{
 
 
@@ -31,15 +40,6 @@ At least one warning is issued immediately when calling \code{dbDisconnect()} on
 already disconnected
 or invalid connection.
 
-}
-\section{Connection lifetime in packages}{
-
-For package-level connection reuse, consider delegating connection lifetime
-management to the pool package. If a package manages a long-lived connection
-itself, any finalizer that calls \code{dbDisconnect()} should keep the connection
-object reachable until the finalizer runs, and should check \code{\link[=dbIsValid]{dbIsValid()}}
-before disconnecting.
-
 }
 
 \examples{

---

This comment was automatically generated by the commit-suggester workflow.

[LeonidasZhak]

Summary

I rechecked this PR locally today and did not make further code changes.

Thanks to maintainers

Thanks again for the guidance on documenting this package-level connection-lifetime pattern.

Issue or motivation

My last note could read as if the PR were fully green. It is not: the branch is locally validated, but the PR is still blocked by one upstream CI failure.

Root cause

At the moment, every visible PR check is successful except rcc: windows-latest (4.5) from run 27012171136. That job fails during the workflow install/setup stage, so the aggregate rcc status for commit 22980a7e remains failing. The branch is not behind main, and the current head already includes the generated man/dbDisconnect.Rd alignment for this doc addition.

Change

No code changes today. I only rechecked the current head and confirmed that the Connection lifetime in packages section matches between R/dbDisconnect.R and man/dbDisconnect.Rd.

Tests

• git diff --check
• R CMD INSTALL .
• R CMD build --no-build-vignettes .
• _R_CHECK_FORCE_SUGGESTS_=false R CMD check --no-manual --ignore-vignettes --no-build-vignettes --no-tests DBI_1.3.0.9010.tar.gz

Scope

I did not change the wording beyond the existing PR, did not touch workflows, and did not push a new commit. I also cannot rerun the upstream failed job from a fork because that requires repository admin rights.