rdbms: Update outdated docs around deprecated reuseConnection()

Bug: T326274
Change-Id: I8f2da12b59f1977177b41548233cae4f441e6146

includes/libs/rdbms/database/DBConnRef.php

@@ -5,21 +5,28 @@ namespace Wikimedia\Rdbms;
 use InvalidArgumentException;
 
 /**
- * Helper class used for automatically marking an IDatabase connection as reusable (once it no
- * longer matters which DB domain is selected) and for deferring the actual network connection
+ * Helper class used for automatically re-using IDatabase connections and lazily
+ * establishing the actual network connection to a database host.
  *
- * This uses an RAII-style pattern where calling code is expected to keep the returned reference
- * handle as a function variable that falls out of scope when no longer needed. This avoids the
- * need for matching reuseConnection() calls for every "return" statement as well as the tedious
- * use of try/finally.
+ * It does this by deferring to ILoadBalancer::getConnectionInternal, which in
+ * turn ensures we share and re-use a single connection for a given database
+ * wherever possible.
+ *
+ * This class previously used an RAII-style pattern where connections would be
+ * claimed from a pool, and then added back to the pool for re-use only after
+ * the calling code's variable for this object went out of scope (a __destruct
+ * got called when the calling function returns or throws). This is no longer
+ * needed today as LoadBalancer now permits re-use internally even for
+ * overlapping callers, where two pieces of code may both obtain their own
+ * DBConnRef object and where both are used alternatingly, and yet still share
+ * the same connection.
  *
  * @par Example:
  * @code
  *     function getRowData() {
- *         $conn = $this->lb->getConnectionRef( DB_REPLICA );
+ *         $conn = $this->lb->getConnection( DB_REPLICA );
  *         $row = $conn->select( ... );
  *         return $row ? (array)$row : false;
- *         // $conn falls out of scope and $this->lb->reuseConnection() gets called
  *     }
  * @endcode
  *

includes/libs/rdbms/loadbalancer/ILoadBalancer.php

@@ -243,7 +243,6 @@ interface ILoadBalancer {
 	 *
 	 * CONN_UNTRACKED_GAUGE and CONN_TRX_AUTOCOMMIT are incompatible.
 	 *
-	 * @see ILoadBalancer::reuseConnection()
 	 * @see ILoadBalancer::getServerAttributes()
 	 *
 	 * @param int $i Specific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index

includes/libs/rdbms/loadbalancer/LoadBalancer.php

@@ -894,7 +894,6 @@ class LoadBalancer implements ILoadBalancerForOwner {
 		//  - a) IDatabase::databasesAreIndependent() returns true (e.g. postgres) and two
 		//       or more database domains have been used during the load balancer's lifetime
 		//  - b) Two or more nested function calls used getConnection() on different domains.
-		//       Normally, callers should use getConnectionRef() instead of getConnection().
 		foreach ( ( $this->conns[$category][$i] ?? [] ) as $poolConn ) {
 			// Check if any required DB domain changes for the new reference are possible
 			// Calling selectDomain() would trigger a reconnect, which will break if a

tests/phpunit/MediaWikiIntegrationTestCase.php

@@ -1713,8 +1713,7 @@ abstract class MediaWikiIntegrationTestCase extends PHPUnit\Framework\TestCase {
 			self::$dbClone = null;
 		}
 
-		// T219673: close any connections from code that failed to call reuseConnection()
-		// or is still holding onto a DBConnRef instance (e.g. in a singleton).
+		// T219673: close any lingering connections.
 		$services->getDBLoadBalancerFactory()->closeAll( __METHOD__ );
 		CloneDatabase::changePrefix( self::$oldTablePrefix );
 

tests/phpunit/includes/Revision/RevisionStoreTest.php

@@ -40,7 +40,7 @@ class RevisionStoreTest extends MediaWikiIntegrationTestCase {
 	private function installMockLoadBalancer( IDatabase $db ) {
 		$lb = $this->createNoOpMock(
 			ILoadBalancer::class,
-			[ 'getConnection', 'getLocalDomainID', 'reuseConnection' ]
+			[ 'getConnection', 'getLocalDomainID' ]
 		);
 
 		$lb->method( 'getConnection' )->willReturn( $db );

tests/phpunit/includes/db/LBFactoryTest.php

@@ -531,8 +531,6 @@ class LBFactoryTest extends MediaWikiIntegrationTestCase {
 			"Correct full table name"
 		);
 
-		$lb->reuseConnection( $db ); // don't care
-
 		$factory->closeAll( __METHOD__ );
 		$factory->destroy();
 	}