* Run an SQL query and return the result. Normally throws a DBQueryError
* on failure. If errors are ignored, returns false instead.
*
+ * If a connection loss is detected, then an attempt to reconnect will be made.
+ * For queries that involve no larger transactions or locks, they will be re-issued
+ * for convenience, provided the connection was re-established.
+ *
* In new code, the query wrappers select(), insert(), update(), delete(),
* etc. should be used where possible, since they give much better DBMS
* independence and automatically quote or validate user input in a variety
* This includes the user table in the query, with the alias "a" available
* for use in field names (e.g. a.user_name).
*
+ * A derived table, defined by the result of selectSQLText(), requires an alias
+ * key and a Subquery instance value which wraps the SQL query, for example:
+ *
+ * [ 'c' => new Subquery( 'SELECT ...' ) ]
+ *
* Joins using parentheses for grouping (since MediaWiki 1.31) may be
* constructed using nested arrays. For example,
*
* doing UNION queries, where the SQL text of each query is needed. In general,
* however, callers outside of Database classes should just use select().
*
+ * @see IDatabase::select()
+ *
* @param string|array $table Table name
* @param string|array $vars Field names
* @param string|array $conds Conditions
* @param string $fname Caller function name
* @param string|array $options Query options
* @param string|array $join_conds Join conditions
- *
- * @return string SQL query string.
- * @see IDatabase::select()
+ * @return string SQL query string
*/
public function selectSQLText(
$table, $vars, $conds = '', $fname = __METHOD__,
* Takes the same arguments as IDatabase::select().
*
* @param string $table Table name
- * @param string $vars Unused
+ * @param string $var Column for which NULL values are not counted [default "*"]
* @param array|string $conds Filters on the table
* @param string $fname Function name for profiling
* @param array $options Options for select
* @throws DBError
*/
public function estimateRowCount(
- $table, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
+ $table, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
);
/**
* @since 1.27 Added $join_conds parameter
*
* @param array|string $tables Table names
- * @param string $vars Unused
+ * @param string $var Column for which NULL values are not counted [default "*"]
* @param array|string $conds Filters on the table
* @param string $fname Function name for profiling
* @param array $options Options for select
* @throws DBError
*/
public function selectRowCount(
- $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
+ $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
);
/**
*/
public function buildIntegerCast( $field );
+ /**
+ * Equivalent to IDatabase::selectSQLText() except wraps the result in Subqyery
+ *
+ * @see IDatabase::selectSQLText()
+ *
+ * @param string|array $table Table name
+ * @param string|array $vars Field names
+ * @param string|array $conds Conditions
+ * @param string $fname Caller function name
+ * @param string|array $options Query options
+ * @param string|array $join_conds Join conditions
+ * @return Subquery
+ * @since 1.31
+ */
+ public function buildSelectSubquery(
+ $table, $vars, $conds = '', $fname = __METHOD__,
+ $options = [], $join_conds = []
+ );
+
/**
* Returns true if DBs are assumed to be on potentially different servers
*
/**
* Determines if the last failure was due to a deadlock
*
+ * Note that during a deadlock, the prior transaction will have been lost
+ *
* @return bool
*/
public function wasDeadlock();
/**
* Determines if the last failure was due to a lock timeout
*
+ * Note that during a lock wait timeout, the prior transaction will have been lost
+ *
* @return bool
*/
public function wasLockTimeout();
/**
- * Determines if the last query error was due to a dropped connection and should
- * be dealt with by pinging the connection and reissuing the query.
+ * Determines if the last query error was due to a dropped connection
+ *
+ * Note that during a connection loss, the prior transaction will have been lost
*
* @return bool
+ * @since 1.31
*/
- public function wasErrorReissuable();
+ public function wasConnectionLoss();
/**
* Determines if the last failure was due to the database being read-only.
*/
public function wasReadOnlyError();
+ /**
+ * Determines if the last query error was due to something outside of the query itself
+ *
+ * Note that the transaction may have been lost, discarding prior writes and results
+ *
+ * @return bool
+ */
+ public function wasErrorReissuable();
+
/**
* Wait for the replica DB to catch up to a given master position
*