Document the serverVersion option in a forward-compatible manner

[derrabus]

Q	A
Type	documentation
Fixed issues	N/A

Summary

The examples that we give for the serverVersion option are all invalid as per #5779, which means they will not work in DBAL 4. This PR changes the affected section of the documentation.

[morozov]

I'd remove the "you should suffix" part as it's controversial. The user should specify the server version verbatim, without adding or removing anything. The documentation could suggest running the following code snippet and using its output as the value of serverVersion:

echo $connection->getServerVersion(), PHP_EOL;

Specific versions of MariaDB could be used as an example. In my case, it produces:

10.11.2-MariaDB-1:10.11.2+maria~ubu2204

Note that this method is private in DBAL 3, so the snippet needs to be adapted.

[derrabus]

Since we're talking about MySQL/MariaDB specifically, we could refer to whatever this query returns:

SELECT VERSION();

WDYT?

[morozov]

Since we're talking about MySQL/MariaDB specifically [...]

Are we? This documentation applies to all platforms for which the DBAL has different implementations for different versions.

[derrabus]

Are we? This documentation applies to all platforms for which the DBAL has different implementations for different versions.

True, but the fact that we're parsing the suffix of a version string is very much specific to MariaDB.

[morozov]

Which is an implementation detail of our version detection logic. Why should users be aware of that?

The whole extent of this feature is providing the server version in the configuration in order to prevent the application from connecting to the database during the calls to Connection::getServerVersion(). The more implementation details we expose via the documentation, the more chances are that the documentation will become obsolete at some point or will have to be continuously changed alongside the changes in supported platforms.

[SenseException]

A private getServerVersion() is also an implementation details in form of a choice to outsource some logic into a private method. Private methods can be removed and shouldn't appear in the docs. Maybe it should be added to the branch for version 4 though.

I'm not sure if we currently have a generic way to get the server version string for the config,

[morozov]

It's a good point. It is private because it's only used for platform detection and is not supposed to be used outside of DBAL. But the thing is that we want to call it in order to use by the DBAL internally.

Anyways, I think this issue doesn't deserve that much discussion. I'm fine with whatever you all decide.

[derrabus]

We need to tell people to use a verbatim version string, but all DBAL APIs that would deliver that string are internal.

I've updated my PR with detailed instructions for MySQL, MariaDB and Postgres on how to get the version string without DBAL. For other platforms, the version string is currently irrelevant, but I've documented the use of the internal APIs for that matter, although I'm not very comfortable with such APIs appearing in the documentation.

btw, I've tried to reply in the thread, but GitHub threw HTTP 500 responses at me when I tried to do so. 😓

[derrabus]

All right, pushing to my branch doesn't work either at the moment. I guess, we need to wait until GitHub got rid of its little hiccup. 😑