/**
* Basic database interface for live and lazy-loaded relation database handles
*
- * @note: IDatabase and DBConnRef should be updated to reflect any changes
+ * @note IDatabase and DBConnRef should be updated to reflect any changes
* @ingroup Database
*/
interface IDatabase {
*/
public function getType();
- /**
- * Open a new connection to the database (closing any existing one)
- *
- * @param string $server Database server host
- * @param string $user Database user name
- * @param string $password Database user password
- * @param string $dbName Database name
- * @return bool
- * @throws DBConnectionError
- */
- public function open( $server, $user, $password, $dbName );
-
/**
* Fetch the next row from the given result object, in object form.
* Fields can be retrieved with $row->fieldname, with fields acting like
* Close the database connection
*
* This should only be called after any transactions have been resolved,
- * aside from read-only transactions (assuming no callbacks are registered).
- * If a transaction is still open anyway, it will be committed if possible.
+ * aside from read-only automatic transactions (assuming no callbacks are registered).
+ * If a transaction is still open anyway, it will be rolled back.
*
* @throws DBError
* @return bool Operation success. true if already closed.
* Escaping of untrusted input used in values of numeric keys should be done via
* IDatabase::addQuotes()
*
+ * Use an empty array, string, or '*' to update all rows.
+ *
* @param string|array $options
*
* Optional: Array of query options. Boolean options are specified by
* errors which wouldn't have occurred in MySQL.
*
* @param string $table The table to replace the row(s) in.
- * @param array $uniqueIndexes Is an array of indexes. Each element may be either
- * a field name or an array of field names
+ * @param array $uniqueIndexes Either a list of fields that define a unique index or
+ * an array of such lists if there are multiple unique indexes defined in the schema
* @param array $rows Can be either a single row to insert, or multiple rows,
- * in the same format as for IDatabase::insert()
+ * in the same format as for IDatabase::insert()
* @param string $fname Calling function name (use __METHOD__) for logs/profiling
* @throws DBError
*/
*
* @param string $table Table name. This will be passed through Database::tableName().
* @param array $rows A single row or list of rows to insert
- * @param array $uniqueIndexes List of single field names or field name tuples
+ * @param array $uniqueIndexes Either a list of fields that define a unique index or
+ * an array of such lists if there are multiple unique indexes defined in the schema
* @param array $set An array of values to SET. For each array element, the
* key gives the field name, and the value gives the data to set that
* field to. The data will be quoted by IDatabase::addQuotes().
*
* This is useful for combining cooperative locks and DB transactions.
*
- * @note: do not assume that *other* IDatabase instances will be AUTOCOMMIT mode
+ * @note do not assume that *other* IDatabase instances will be AUTOCOMMIT mode
*
* The callback takes the following arguments:
* - How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK)
*
* Updates will execute in the order they were enqueued.
*
- * @note: do not assume that *other* IDatabase instances will be AUTOCOMMIT mode
+ * @note do not assume that *other* IDatabase instances will be AUTOCOMMIT mode
*
* The callback takes the following arguments:
* - How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_IDLE)
* - The failures are from contention solvable via onTransactionPreCommitOrIdle()
* - The failures are deadlocks; the RDBMs usually discard the whole transaction
*
- * @note: callers must use additional measures for situations involving two or more
+ * @note callers must use additional measures for situations involving two or more
* (peer) transactions (e.g. updating two database servers at once). The transaction
* and savepoint logic of this method only applies to this specific IDatabase instance.
*
* corresponding startAtomic() implicitly started a transaction, that
* transaction is rolled back.
*
- * @note: callers must use additional measures for situations involving two or more
+ * @note callers must use additional measures for situations involving two or more
* (peer) transactions (e.g. updating two database servers at once). The transaction
* and savepoint logic of startAtomic() are bound to specific IDatabase instances.
*