MediaWiki  1.33.0
Wikimedia\Rdbms\MaintainableDBConnRef Class Reference

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. More...

Inheritance diagram for Wikimedia\Rdbms\MaintainableDBConnRef:
Collaboration diagram for Wikimedia\Rdbms\MaintainableDBConnRef:

Public Member Functions

 deadlockLoop ()
 Perform a deadlock-prone transaction. More...
 
 dropTable ( $tableName, $fName=__METHOD__)
 Delete a table. More...
 
 duplicateTableStructure ( $oldName, $newName, $temporary=false, $fname=__METHOD__)
 Creates a new table with structure copied from existing table. More...
 
 fieldInfo ( $table, $field)
 mysql_fetch_field() wrapper Returns false if the field doesn't exist More...
 
 indexUnique ( $table, $index)
 Determines if a given index is unique. More...
 
 listTables ( $prefix=null, $fname=__METHOD__)
 List all tables on the database. More...
 
 listViews ( $prefix=null, $fname=__METHOD__)
 Lists all the VIEWs in the database. More...
 
 lockTables (array $read, array $write, $method)
 Lock specific tables. More...
 
 sourceFile ( $filename, callable $lineCallback=null, callable $resultCallback=null, $fname=false, callable $inputCallback=null)
 Read and execute SQL commands from a file. More...
 
 sourceStream ( $fp, callable $lineCallback=null, callable $resultCallback=null, $fname=__METHOD__, callable $inputCallback=null)
 Read and execute commands from an open file handle. More...
 
 streamStatementEnd (&$sql, &$newLine)
 Called by sourceStream() to check if we've reached a statement end. More...
 
 tableLocksHaveTransactionScope ()
 Checks if table locks acquired by lockTables() are transaction-bound in their scope. More...
 
 tableName ( $name, $format='quoted')
 Format a table name ready for use in constructing an SQL query. More...
 
 tableNames ()
 Fetch a number of table names into an array This is handy when you need to construct SQL for joins. More...
 
 tableNamesN ()
 Fetch a number of table names into an zero-indexed numerical array This is handy when you need to construct SQL for joins. More...
 
 textFieldSize ( $table, $field)
 Returns the size of a text field, or -1 for "unlimited". More...
 
 unlockTables ( $method)
 Unlock all tables locked via lockTables() More...
 
- Public Member Functions inherited from Wikimedia\Rdbms\DBConnRef
 __call ( $name, array $arguments)
 
 __construct (ILoadBalancer $lb, $conn, $role)
 
 __destruct ()
 Clean up the connection when out of scope. More...
 
 addIdentifierQuotes ( $s)
 Quotes an identifier, in order to make user controlled input safe. More...
 
 addQuotes ( $s)
 Adds quotes and backslashes. More...
 
 affectedRows ()
 Get the number of rows affected by the last write query. More...
 
 aggregateValue ( $valuedata, $valuename='value')
 Return aggregated value alias. More...
 
 anyChar ()
 Returns a token for buildLike() that denotes a '_' to be used in a LIKE query. More...
 
 anyString ()
 Returns a token for buildLike() that denotes a '' to be used in a LIKE query. More...
 
 assertNoOpenTransactions ()
 Assert that all explicit transactions or atomic sections have been closed. More...
 
 begin ( $fname=__METHOD__, $mode=IDatabase::TRANSACTION_EXPLICIT)
 Begin a transaction. More...
 
 bitAnd ( $fieldLeft, $fieldRight)
 
 bitNot ( $field)
 
 bitOr ( $fieldLeft, $fieldRight)
 
 bufferResults ( $buffer=null)
 Turns buffering of SQL result sets on (true) or off (false). More...
 
 buildConcat ( $stringList)
 Build a concatenation list to feed into a SQL query. More...
 
 buildGroupConcatField ( $delim, $table, $field, $conds='', $join_conds=[])
 Build a GROUP_CONCAT or equivalent statement for a query. More...
 
 buildIntegerCast ( $field)
 
 buildLike ()
 LIKE statement wrapper, receives a variable-length argument list with parts of pattern to match containing either string literals that will be escaped or tokens returned by anyChar() or anyString(). More...
 
 buildSelectSubquery ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Equivalent to IDatabase::selectSQLText() except wraps the result in Subqyery. More...
 
 buildStringCast ( $field)
 
 buildSubstring ( $input, $startPosition, $length=null)
 
 cancelAtomic ( $fname=__METHOD__, AtomicSectionIdentifier $sectionId=null)
 Cancel an atomic section of SQL statements. More...
 
 clearFlag ( $flag, $remember=self::REMEMBER_NOTHING)
 Clear a flag for this connection. More...
 
 close ()
 Close the database connection. More...
 
 commit ( $fname=__METHOD__, $flush='')
 Commits a transaction previously started using begin(). More...
 
 conditional ( $cond, $trueVal, $falseVal)
 Returns an SQL expression for a simple conditional. More...
 
 databasesAreIndependent ()
 Returns true if DBs are assumed to be on potentially different servers. More...
 
 dataSeek ( $res, $row)
 Change the position of the cursor in a result object. More...
 
 dbSchema ( $schema=null)
 Get/set the db schema. More...
 
 decodeBlob ( $b)
 Some DBMSs return a special placeholder object representing blob fields in result objects. More...
 
 decodeExpiry ( $expiry, $format=TS_MW)
 Decode an expiry time into a DBMS independent format. More...
 
 delete ( $table, $conds, $fname=__METHOD__)
 DELETE query wrapper. More...
 
 deleteJoin ( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname=__METHOD__)
 DELETE where the condition is a join. More...
 
 doAtomicSection ( $fname, callable $callback, $cancelable=self::ATOMIC_NOT_CANCELABLE)
 Perform an atomic section of reversable SQL statements from a callback. More...
 
 doneWrites ()
 Returns true if the connection may have been used for write queries. More...
 
 encodeBlob ( $b)
 Some DBMSs have a special format for inserting into blob fields, they don't allow simple quoted strings to be inserted. More...
 
 encodeExpiry ( $expiry)
 Encode an expiry time into the DBMS dependent format. More...
 
 endAtomic ( $fname=__METHOD__)
 Ends an atomic section of SQL statements. More...
 
 estimateRowCount ( $table, $vars=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Estimate the number of rows in dataset. More...
 
 explicitTrxActive ()
 
 fetchObject ( $res)
 Fetch the next row from the given result object, in object form. More...
 
 fetchRow ( $res)
 Fetch the next row from the given result object, in associative array form. More...
 
 fieldExists ( $table, $field, $fname=__METHOD__)
 Determines whether a field exists in a table. More...
 
 fieldName ( $res, $n)
 Get a field name in a result object. More...
 
 flushSnapshot ( $fname=__METHOD__)
 Commit any transaction but error out if writes or callbacks are pending. More...
 
 freeResult ( $res)
 Free a result object returned by query() or select(). More...
 
 getDBname ()
 Get the current DB name. More...
 
 getDomainID ()
 Return the currently selected domain ID. More...
 
 getFlag ( $flag)
 Returns a boolean whether the flag $flag is set for this connection. More...
 
 getInfinity ()
 Find out when 'infinity' is. More...
 
 getLag ()
 Get the amount of replication lag for this database server. More...
 
 getLBInfo ( $name=null)
 Get properties passed down from the server info array of the load balancer. More...
 
 getMasterPos ()
 Get the position of this master. More...
 
 getProperty ( $name)
 
 getReferenceRole ()
 
 getReplicaPos ()
 Get the replication position of this replica DB. More...
 
 getScopedLockAndFlush ( $lockKey, $fname, $timeout)
 Acquire a named lock, flush any transaction, and return an RAII style unlocker object. More...
 
 getServer ()
 Get the server hostname or IP address. More...
 
 getServerInfo ()
 A string describing the current software version, and possibly other details in a user-friendly way. More...
 
 getServerUptime ()
 Determines how long the server has been up. More...
 
 getServerVersion ()
 A string describing the current software version, like from mysql_get_server_info(). More...
 
 getSessionLagStatus ()
 Get the replica DB lag when the current transaction started or a general lag estimate if not transaction is active. More...
 
 getSoftwareLink ()
 Returns a wikitext link to the DB's website, e.g., return "[https://www.mysql.com/ MySQL]"; Should at least contain plain text, if for some reason your database has no website. More...
 
 getType ()
 Get the type of the DBMS, as it appears in $wgDBtype. More...
 
 getWikiID ()
 Alias for getDomainID() More...
 
 implicitGroupby ()
 Returns true if this database does an implicit sort when doing GROUP BY. More...
 
 implicitOrderby ()
 Returns true if this database does an implicit order by when the column has an index For example: SELECT page_title FROM page LIMIT 1. More...
 
 indexExists ( $table, $index, $fname=__METHOD__)
 Determines whether an index exists Usually throws a DBQueryError on failure If errors are explicitly ignored, returns NULL on failure. More...
 
 insert ( $table, $a, $fname=__METHOD__, $options=[])
 INSERT wrapper, inserts an array into a table. More...
 
 insertId ()
 Get the inserted value of an auto-increment row. More...
 
 insertSelect ( $destTable, $srcTable, $varMap, $conds, $fname=__METHOD__, $insertOptions=[], $selectOptions=[], $selectJoinConds=[])
 INSERT SELECT wrapper. More...
 
 isOpen ()
 Is a connection to the database open? More...
 
 isReadOnly ()
 
 lastDoneWrites ()
 Returns the last time the connection may have been used for write queries. More...
 
 lastErrno ()
 Get the last error number. More...
 
 lastError ()
 Get a description of the last error. More...
 
 lastQuery ()
 Return the last query that went through IDatabase::query() More...
 
 lock ( $lockName, $method, $timeout=5)
 Acquire a named lock. More...
 
 lockForUpdate ( $table, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Lock all rows meeting the given conditions/options FOR UPDATE. More...
 
 lockIsFree ( $lockName, $method)
 Check to see if a named lock is not locked by any thread (non-blocking) More...
 
 makeList ( $a, $mode=self::LIST_COMMA)
 Makes an encoded list of strings from an array. More...
 
 makeWhereFrom2d ( $data, $baseKey, $subKey)
 Build a partial where clause from a 2-d array such as used for LinkBatch. More...
 
 masterPosWait (DBMasterPos $pos, $timeout)
 Wait for the replica DB to catch up to a given master position. More...
 
 maxListLen ()
 Return the maximum number of items allowed in a list, or 0 for unlimited. More...
 
 namedLocksEnqueue ()
 Check to see if a named lock used by lock() use blocking queues. More...
 
 nextSequenceValue ( $seqName)
 Deprecated method, calls should be removed. More...
 
 numFields ( $res)
 Get the number of fields in a result object. More...
 
 numRows ( $res)
 Get the number of rows in a query result. More...
 
 onTransactionCommitOrIdle (callable $callback, $fname=__METHOD__)
 Run a callback as soon as there is no transaction pending. More...
 
 onTransactionIdle (callable $callback, $fname=__METHOD__)
 Alias for onTransactionCommitOrIdle() for backwards-compatibility. More...
 
 onTransactionPreCommitOrIdle (callable $callback, $fname=__METHOD__)
 Run a callback before the current transaction commits or now if there is none. More...
 
 onTransactionResolution (callable $callback, $fname=__METHOD__)
 Run a callback as soon as the current transaction commits or rolls back. More...
 
 pendingWriteCallers ()
 Get the list of method names that did write queries for this transaction. More...
 
 pendingWriteQueryDuration ( $type=self::ESTIMATE_TOTAL)
 Get the time spend running write queries for this transaction. More...
 
 pendingWriteRowsAffected ()
 Get the number of affected rows from pending write queries. More...
 
 ping (&$rtt=null)
 Ping the server and try to reconnect if it there is no connection. More...
 
 preCommitCallbacksPending ()
 
 query ( $sql, $fname=__METHOD__, $flags=0)
 Run an SQL query and return the result. More...
 
 replace ( $table, $uniqueIndexes, $rows, $fname=__METHOD__)
 REPLACE query wrapper. More...
 
 restoreFlags ( $state=self::RESTORE_PRIOR)
 Restore the flags to their prior state before the last setFlag/clearFlag call. More...
 
 rollback ( $fname=__METHOD__, $flush='')
 Rollback a transaction previously started using begin(). More...
 
 select ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Execute a SELECT query constructed using the various parameters provided. More...
 
 selectDB ( $db)
 Change the current database. More...
 
 selectDomain ( $domain)
 Set the current domain (database, schema, and table prefix) More...
 
 selectField ( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
 A SELECT wrapper which returns a single field from a single result row. More...
 
 selectFieldValues ( $table, $var, $cond='', $fname=__METHOD__, $options=[], $join_conds=[])
 A SELECT wrapper which returns a list of single field values from result rows. More...
 
 selectRow ( $table, $vars, $conds, $fname=__METHOD__, $options=[], $join_conds=[])
 Single row SELECT wrapper. More...
 
 selectRowCount ( $tables, $vars=' *', $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Get the number of rows in dataset. More...
 
 selectSQLText ( $table, $vars, $conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 The equivalent of IDatabase::select() except that the constructed SQL is returned, instead of being immediately executed. More...
 
 serverIsReadOnly ()
 
 setBigSelects ( $value=true)
 Allow or deny "big selects" for this session only. More...
 
 setFlag ( $flag, $remember=self::REMEMBER_NOTHING)
 Set a flag for this connection. More...
 
 setIndexAliases (array $aliases)
 Convert certain index names to alternative names before querying the DB. More...
 
 setLazyMasterHandle (IDatabase $conn)
 Set a lazy-connecting DB handle to the master DB (for replication status purposes) More...
 
 setLBInfo ( $name, $value=null)
 Set the LB info array, or a member of it. More...
 
 setSchemaVars ( $vars)
 Set variables to be used in sourceFile/sourceStream, in preference to the ones in $GLOBALS. More...
 
 setSessionOptions (array $options)
 Override database's default behavior. More...
 
 setTableAliases (array $aliases)
 Make certain table names use their own database, schema, and table prefix when passed into SQL queries pre-escaped and without a qualified database name. More...
 
 setTransactionListener ( $name, callable $callback=null)
 Run a callback after each time any transaction commits or rolls back. More...
 
 startAtomic ( $fname=__METHOD__, $cancelable=IDatabase::ATOMIC_NOT_CANCELABLE)
 Begin an atomic section of SQL statements. More...
 
 strreplace ( $orig, $old, $new)
 Returns a command for str_replace function in SQL query. More...
 
 tableExists ( $table, $fname=__METHOD__)
 Query whether a given table exists. More...
 
 tablePrefix ( $prefix=null)
 Get/set the table prefix. More...
 
 timestamp ( $ts=0)
 Convert a timestamp in one of the formats accepted by wfTimestamp() to the format used for inserting into timestamp fields in this DBMS. More...
 
 timestampOrNull ( $ts=null)
 Convert a timestamp in one of the formats accepted by wfTimestamp() to the format used for inserting into timestamp fields in this DBMS. More...
 
 trxLevel ()
 Gets the current transaction level. More...
 
 trxTimestamp ()
 Get the UNIX timestamp of the time that the transaction was established. More...
 
 unionConditionPermutations ( $table, $vars, array $permute_conds, $extra_conds='', $fname=__METHOD__, $options=[], $join_conds=[])
 Construct a UNION query for permutations of conditions. More...
 
 unionQueries ( $sqls, $all)
 Construct a UNION query This is used for providing overload point for other DB abstractions not compatible with the MySQL syntax. More...
 
 unionSupportsOrderAndLimit ()
 Returns true if current database backend supports ORDER BY or LIMIT for separate subqueries within the UNION construct. More...
 
 unlock ( $lockName, $method)
 Release a lock. More...
 
 update ( $table, $values, $conds, $fname=__METHOD__, $options=[])
 UPDATE wrapper. More...
 
 upsert ( $table, array $rows, $uniqueIndexes, array $set, $fname=__METHOD__)
 INSERT ON DUPLICATE KEY UPDATE wrapper, upserts an array into a table. More...
 
 wasConnectionLoss ()
 Determines if the last query error was due to a dropped connection. More...
 
 wasDeadlock ()
 Determines if the last failure was due to a deadlock. More...
 
 wasErrorReissuable ()
 Determines if the last query error was due to something outside of the query itself. More...
 
 wasLockTimeout ()
 Determines if the last failure was due to a lock timeout. More...
 
 wasReadOnlyError ()
 Determines if the last failure was due to the database being read-only. More...
 
 writesOrCallbacksPending ()
 Whether there is a transaction open with either possible write queries or unresolved pre-commit/commit/resolution callbacks pending. More...
 
 writesPending ()
 
- Public Member Functions inherited from Wikimedia\Rdbms\IDatabase
 buildSubString ( $input, $startPosition, $length=null)
 Build a SUBSTRING function. More...
 

Additional Inherited Members

- Public Attributes inherited from Wikimedia\Rdbms\DBConnRef
const FLD_DOMAIN = 2
 
const FLD_FLAGS = 3
 
const FLD_GROUP = 1
 
const FLD_INDEX = 0
 
- Protected Member Functions inherited from Wikimedia\Rdbms\DBConnRef
 assertRoleAllowsWrites ()
 Error out if the role is not DB_MASTER. More...
 

Detailed Description

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.

Note
: proxy methods are defined explicity to avoid interface errors
Since
1.29

Definition at line 13 of file MaintainableDBConnRef.php.

Member Function Documentation

◆ deadlockLoop()

Wikimedia\Rdbms\MaintainableDBConnRef::deadlockLoop ( )

Perform a deadlock-prone transaction.

This function invokes a callback function to perform a set of write queries. If a deadlock occurs during the processing, the transaction will be rolled back and the callback function will be called again.

Avoid using this method outside of Job or Maintenance classes.

Usage: $dbw->deadlockLoop( callback, ... );

Extra arguments are passed through to the specified callback function. This method requires that no transactions are already active to avoid causing premature commits or exceptions.

Returns whatever the callback function returned on its successful, iteration, or false on error, for example if the retry limit was reached.

Returns
mixed
Exceptions
DBUnexpectedError
Exception

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 56 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call(), and Wikimedia\Rdbms\DBConnRef\assertRoleAllowsWrites().

◆ dropTable()

Wikimedia\Rdbms\MaintainableDBConnRef::dropTable (   $tableName,
  $fName = __METHOD__ 
)

Delete a table.

Parameters
string$tableName
string$fName
Returns
bool|ResultWrapper

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 50 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call(), and Wikimedia\Rdbms\DBConnRef\assertRoleAllowsWrites().

◆ duplicateTableStructure()

Wikimedia\Rdbms\MaintainableDBConnRef::duplicateTableStructure (   $oldName,
  $newName,
  $temporary = false,
  $fname = __METHOD__ 
)

Creates a new table with structure copied from existing table.

Note that unlike most database abstraction functions, this function does not automatically append database prefix, because it works at a lower abstraction level. The table names passed to this function shall not be quoted (this function calls addIdentifierQuotes() when needed).

Parameters
string$oldNameName of table whose structure should be copied
string$newNameName of table to be created
bool$temporaryWhether the new table should be temporary
string$fnameCalling function name
Returns
bool True if operation was successful
Exceptions
RuntimeException

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 74 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call(), and Wikimedia\Rdbms\DBConnRef\assertRoleAllowsWrites().

◆ fieldInfo()

Wikimedia\Rdbms\MaintainableDBConnRef::fieldInfo (   $table,
  $field 
)

mysql_fetch_field() wrapper Returns false if the field doesn't exist

Parameters
string$tableTable name
string$fieldField name
Returns
Field

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 106 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ indexUnique()

Wikimedia\Rdbms\MaintainableDBConnRef::indexUnique (   $table,
  $index 
)

Determines if a given index is unique.

Parameters
string$table
string$index
Returns
bool

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 98 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ listTables()

Wikimedia\Rdbms\MaintainableDBConnRef::listTables (   $prefix = null,
  $fname = __METHOD__ 
)

List all tables on the database.

Parameters
string | null$prefixOnly show tables with this prefix, e.g. mw_
string$fnameCalling function name
Exceptions
DBError
Returns
array

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 102 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ listViews()

Wikimedia\Rdbms\MaintainableDBConnRef::listViews (   $prefix = null,
  $fname = __METHOD__ 
)

Lists all the VIEWs in the database.

Parameters
string | null$prefixOnly show VIEWs with this prefix, eg. unit_test_
string$fnameName of calling function
Exceptions
RuntimeException
Returns
array

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 62 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ lockTables()

Wikimedia\Rdbms\MaintainableDBConnRef::lockTables ( array  $read,
array  $write,
  $method 
)

Lock specific tables.

Any pending transaction should be resolved before calling this method, since: a) Doing so resets any REPEATABLE-READ snapshot of the data to a fresh one. b) Previous row and table locks from the transaction or session may be released by LOCK TABLES, which may be unsafe for the changes in such a transaction. c) The main use case of lockTables() is to avoid deadlocks and timeouts by locking entire tables in order to do long-running, batched, and lag-aware, updates. Batching and replication lag checks do not work when all the updates happen in a transaction.

Always get all relevant table locks up-front in one call, since LOCK TABLES might release any prior table locks on some RDBMes (e.g MySQL).

For compatibility, callers should check tableLocksHaveTransactionScope() before using this method. If locks are scoped specifically to transactions then caller must either:

  • a) Start a new transaction and acquire table locks for the scope of that transaction, doing all row updates within that transaction. It will not be possible to update rows in batches; this might result in high replication lag.
  • b) Forgo table locks entirely and avoid calling this method. Careful use of hints like LOCK IN SHARE MODE and FOR UPDATE and the use of query batching may be preferrable to using table locks with a potentially large transaction. Use of MySQL and Postges style REPEATABLE-READ (Snapshot Isolation with or without First-Committer-Rule) can also be considered for certain tasks that require a consistent view of entire tables.

If session scoped locks are not supported, then calling lockTables() will trigger startAtomic(), with unlockTables() triggering endAtomic(). This will automatically start a transaction if one is not already present and cause the locks to be released when the transaction finishes (normally during the unlockTables() call).

In any case, avoid using begin()/commit() in code that runs while such table locks are acquired, as that breaks in case when a transaction is needed. The startAtomic() and endAtomic() methods are safe, however, since they will join any existing transaction.

Parameters
array$readArray of tables to lock for read access
array$writeArray of tables to lock for write access
string$methodName of caller
Returns
bool
Since
1.29

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 86 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call(), and Wikimedia\Rdbms\DBConnRef\assertRoleAllowsWrites().

◆ sourceFile()

Wikimedia\Rdbms\MaintainableDBConnRef::sourceFile (   $filename,
callable  $lineCallback = null,
callable  $resultCallback = null,
  $fname = false,
callable  $inputCallback = null 
)

Read and execute SQL commands from a file.

Returns true on success, error string or exception on failure (depending on object's error ignore settings).

Parameters
string$filenameFile name to open
callable | null$lineCallbackOptional function called before reading each line
callable | null$resultCallbackOptional function called for each MySQL result
bool | string$fnameCalling function name or false if name should be generated dynamically using $filename
callable | null$inputCallbackOptional function called for each complete line sent
Returns
bool|string
Exceptions
Exception

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 26 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call(), and Wikimedia\Rdbms\DBConnRef\assertRoleAllowsWrites().

◆ sourceStream()

Wikimedia\Rdbms\MaintainableDBConnRef::sourceStream (   $fp,
callable  $lineCallback = null,
callable  $resultCallback = null,
  $fname = __METHOD__,
callable  $inputCallback = null 
)

Read and execute commands from an open file handle.

Returns true on success, error string or exception on failure (depending on object's error ignore settings).

Parameters
resource$fpFile handle
callable | null$lineCallbackOptional function called before reading each query
callable | null$resultCallbackOptional function called for each MySQL result
string$fnameCalling function name
callable | null$inputCallbackOptional function called for each complete query sent
Returns
bool|string

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 38 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call(), and Wikimedia\Rdbms\DBConnRef\assertRoleAllowsWrites().

◆ streamStatementEnd()

Wikimedia\Rdbms\MaintainableDBConnRef::streamStatementEnd ( $sql,
$newLine 
)

Called by sourceStream() to check if we've reached a statement end.

Parameters
string&$sqlSQL assembled so far
string&$newLineNew line about to be added to $sql
Returns
bool Whether $newLine contains end of the statement

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 70 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ tableLocksHaveTransactionScope()

Wikimedia\Rdbms\MaintainableDBConnRef::tableLocksHaveTransactionScope ( )

Checks if table locks acquired by lockTables() are transaction-bound in their scope.

Transaction-bound table locks will be released when the current transaction terminates. Table locks that are not bound to a transaction are not effected by BEGIN/COMMIT/ROLLBACK and will last until either lockTables()/unlockTables() is called or the TCP connection to the database is closed.

Returns
bool
Since
1.29

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 82 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ tableName()

Wikimedia\Rdbms\MaintainableDBConnRef::tableName (   $name,
  $format = 'quoted' 
)

Format a table name ready for use in constructing an SQL query.

This does two important things: it quotes the table names to clean them up, and it adds a table prefix if only given a table name with no quotes.

All functions of this object which require a table name call this function themselves. Pass the canonical name to such functions. This is only needed when calling query() directly.

Note
This function does not sanitize user input. It is not safe to use this function to escape user input.
Parameters
string$nameDatabase table name
string$formatOne of: quoted - Automatically pass the table name through addIdentifierQuotes() so that it can be used in a query. raw - Do not add identifier quotes to the table name
Returns
string Full database name

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 14 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ tableNames()

Wikimedia\Rdbms\MaintainableDBConnRef::tableNames ( )

Fetch a number of table names into an array This is handy when you need to construct SQL for joins.

Example: list( $user, $watchlist ) = $dbr->tableNames( 'user', 'watchlist' ) ); $sql = "SELECT wl_namespace, wl_title FROM $watchlist, $user WHERE wl_user=user_id AND wl_user=$nameWithQuotes";

Returns
array

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 18 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ tableNamesN()

Wikimedia\Rdbms\MaintainableDBConnRef::tableNamesN ( )

Fetch a number of table names into an zero-indexed numerical array This is handy when you need to construct SQL for joins.

Example: list( $user, $watchlist ) = $dbr->tableNamesN( 'user', 'watchlist' ); $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user WHERE wl_user=user_id AND wl_user=$nameWithQuotes";

Returns
array

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 22 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ textFieldSize()

Wikimedia\Rdbms\MaintainableDBConnRef::textFieldSize (   $table,
  $field 
)

Returns the size of a text field, or -1 for "unlimited".

Parameters
string$table
string$field
Returns
int

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 66 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call().

◆ unlockTables()

Wikimedia\Rdbms\MaintainableDBConnRef::unlockTables (   $method)

Unlock all tables locked via lockTables()

If table locks are scoped to transactions, then locks might not be released until the transaction ends, which could happen after this method is called.

Parameters
string$methodThe caller
Returns
bool
Since
1.29

Implements Wikimedia\Rdbms\IMaintainableDatabase.

Definition at line 92 of file MaintainableDBConnRef.php.

References Wikimedia\Rdbms\DBConnRef\__call(), and Wikimedia\Rdbms\DBConnRef\assertRoleAllowsWrites().


The documentation for this class was generated from the following file: