Hello,

We have two breaking changes to announce. Breaking change to Rdbms Database subclasses

There are no Database subclasses currently known in Codesearch (besides those built-in to core). But, since the class is documented as "stable to extend" in API, an announcement is in order.

First, an explanation on what is happening. Currently, queries flow in the Rdbms library as follows: When Database::select() or similar is called (directly, or via the query builders), the Rdbms library internally builds the SQL text and then calls the general-purpose function Database::query(). Subsequently, ::query() then runs several regexes over the SQL text to figure out information about this query (which tables are affected, whether it’s a write query, what the query “verb” is, and so on). This is taxing and slow. The appservers at WMF, for example, spend 0.34% of CPU on web requests just to extract information from already-formatted SQL queries for logging purposes. This logic drastically reduces readability and maintainability of Rdbms internals.

To fix this, we've internally introduced a new class called Query, to represent the SQL text in a more structured way in the first place. This avoids having to first format structure data into SQL text only to reverse-engineer it right afterwards.

This change requires changing the protected Database::executeQuery() method to no longer accept a string argument and instead require a Query object. Additionally IDatabase::getTempTableWrites() has become a private method. See the patch https://gerrit.wikimedia.org/r/c/mediawiki/core/+/910756 or the ticket https://phabricator.wikimedia.org/T326181 for more information.

The public Database::query() method continues to support a string argument, but now also supports a Query object. When given a string, it falls back to the old regexes to extract and create a Query object. With the newly introduced UnionQueryBuilder, we believe there are no longer cases where MediaWiki extensions have to call Database::query, and can instead adopt query builders for all their queries. Direct calls to Database::query outside of MediaWiki core are now highly discouraged.

Breaking change to typehints of IDatabase

Many parts of core typehint to IDatabase, but most times these always return a replica database. For example, ApiBase::getDB(). This means the interface technically allows calling insert(), and this is indeed valid, but would also immediately throw a fatal error once the method is entered. Going forward, most of these will be typehinted to IReadableDatabase instead, which is a narrower interface (34 public methods instead of 83).

This is not a breaking change in practice, because calls to those methods would already produce an error, but the typehint makes it official now. This https://gerrit.wikimedia.org/r/c/mediawiki/core/+/911269 is the patch changing ApiBase::getDB(), and we expect more such changes to other parts of MediaWiki over the coming months. Those will not be individually announced.

Best