Doc + PHP Doc should clarify QueryBuilder features not supported across databases

[andrerom]

Bug Report

Q	A
BC Break	yes/no (depends on resolution)
Version	2.x

Summary

Like most users (#2451, #2610, ..) expectations with DBAL, including QueryBuilder, is that it handles Database differences.

<op> Why otherwise would we bother abstracting queries with QueryBuilder? For anyone accustomed to SQL it does not exactly make it easier to read. </op> 🤷‍♂️

Anyways..

• While Query Builder states this in class doc, this is not where most users starts out
• Solution for this seems to be kind of planned for 3.0, however for 2.x doc can be improved

So suggestion here is to make this more clear on doc and PHP doc that covers features where users needs to be aware it depends on database if it is supported or not.

Current behaviour

Features on QueryBuilder is not supported across databases.

How to reproduce

Use features not supported on some databases, for example alias argument on ->update().

Expected behaviour

Either:
A. DBAL handles this for us
B. Doc is clear on every single feature where this can be a problem (ok'ish while waiting for A)
C. Or features not supported across databases are deprecated and documented as such

If A is planned for 3.0 we can update doc in 2.x according to B.

In case of update() alias argument it can be clarified in these places:

• https://www.doctrine-project.org/projects/doctrine-dbal/en/2.8/reference/query-builder.html#set-clause
• https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Query/QueryBuilder.php#L550-L561

Can also remove alias usage in this examples to avoid (miss-)leading people to use this:

• https://github.com/doctrine/dbal/blob/master/lib/Doctrine/DBAL/Query/QueryBuilder.php#L744-L789

Which other QueryBuilder features are affected?

[morozov]

There's endless potential for improvement, especially in the documentation. A pull request is welcome.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.