rdbms: clean up $groups logic in LoadBalancer and expand comments

[lhc/web/wiklou.git] / includes / libs / rdbms / database / DBConnRef.php

diff --git a/includes/libs/rdbms/database/DBConnRef.php b/includes/libs/rdbms/database/DBConnRef.php
index f3ab1c5..fe3d437 100644 (file)
--- a/includes/libs/rdbms/database/DBConnRef.php
+++ b/includes/libs/rdbms/database/DBConnRef.php
@@ -5,8 +5,23 @@ namespace Wikimedia\Rdbms;
 use InvalidArgumentException;
 
 /**
- * Helper class to handle automatically marking connections as reusable (via RAII pattern)
- * as well handling deferring the actual network connection until the handle is used
+ * 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
+ *
+ * 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.
+ *
+ * @par Example:
+ * @code
+ *     function getRowData() {
+ *         $conn = $this->lb->getConnectedRef( DB_REPLICA );
+ *         $row = $conn->select( ... );
+ *         return $row ? (array)$row : false;
+ *         // $conn falls out of scope and $this->lb->reuseConnection() gets called
+ *     }
+ * @endcode
  *
  * @ingroup Database
  * @since 1.22
@@ -35,7 +50,7 @@ class DBConnRef implements IDatabase {
        public function __construct( ILoadBalancer $lb, $conn, $role ) {
                $this->lb = $lb;
                $this->role = $role;
-               if ( $conn instanceof Database ) {
+               if ( $conn instanceof IDatabase && !( $conn instanceof DBConnRef ) ) {
                        $this->conn = $conn; // live handle
                } elseif ( is_array( $conn ) && count( $conn ) >= 4 && $conn[self::FLD_DOMAIN] !== false ) {
                        $this->params = $conn;
@@ -46,8 +61,8 @@ class DBConnRef implements IDatabase {
 
        function __call( $name, array $arguments ) {
                if ( $this->conn === null ) {
-                       list( $db, $groups, $wiki, $flags ) = $this->params;
-                       $this->conn = $this->lb->getConnection( $db, $groups, $wiki, $flags );
+                       list( $index, $groups, $wiki, $flags ) = $this->params;
+                       $this->conn = $this->lb->getConnection( $index, $groups, $wiki, $flags );
                }
 
                return $this->conn->$name( ...$arguments );
@@ -211,6 +226,19 @@ class DBConnRef implements IDatabase {
        }
 
        public function getType() {
+               if ( $this->conn === null ) {
+                       // Avoid triggering a database connection
+                       if ( $this->params[self::FLD_INDEX] === ILoadBalancer::DB_MASTER ) {
+                               $index = $this->lb->getWriterIndex();
+                       } else {
+                               $index = $this->params[self::FLD_INDEX];
+                       }
+                       if ( $index >= 0 ) {
+                               // In theory, if $index is DB_REPLICA, the type could vary
+                               return $this->lb->getServerType( $index );
+                       }
+               }
+
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
@@ -304,6 +332,10 @@ class DBConnRef implements IDatabase {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
+       public function limitResult( $sql, $limit, $offset = false ) {
+               return $this->__call( __FUNCTION__, func_get_args() );
+       }
+
        public function selectRow(
                $table, $vars, $conds, $fname = __METHOD__,
                $options = [], $join_conds = []
@@ -444,7 +476,7 @@ class DBConnRef implements IDatabase {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
-       public function buildLike() {
+       public function buildLike( $param ) {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
@@ -723,6 +755,19 @@ class DBConnRef implements IDatabase {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
+       public function __toString() {
+               if ( $this->conn === null ) {
+                       // spl_object_id is PHP >= 7.2
+                       $id = function_exists( 'spl_object_id' )
+                               ? spl_object_id( $this )
+                               : spl_object_hash( $this );
+
+                       return $this->getType() . ' object #' . $id;
+               }
+
+               return $this->__call( __FUNCTION__, func_get_args() );
+       }
+
        /**
         * Error out if the role is not DB_MASTER
         *