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
--
*Amir Sarabadani (he/him)*
Staff Database Architect
Wikimedia Foundation <https://wikimediafoundation.org/>
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
--
*Amir Sarabadani (he/him)*
Staff Database Architect
Wikimedia Foundation <https://wikimediafoundation.org/>