Improve docs on Persistent (DB) Connections

[AllenJB]

See #4540

[kamil-tekiela]

Though I may add that this is a little bit ambiguous for a PHP manual. If anyone is using PDO persistent connection right now then I assume they already know how to keep the connections clean or they don't run into this problem much. So just saying that PDO doesn't do any clean up isn't as useful as it could be. For a new user some questions arise: what is this clean up? how can I do it manually? when do I need to do it?

[AllenJB]

The primary reason for this change is, as per the linked issue, mysqli has a page detailing the persistent connection management it does.

As a user I know mysqli and PDO MySQL use the same backend - mysqlnd. From that standpoint my first assumption was that PDO MySQL must do the same management. But this turns out not to be the case.

Based on my experience it's false to assume that everyone using persistent connections is aware of the potential issues with them. I've seen plenty of users enable them because they've seen it recommended either for performance of to solve problems with "too many connections" errors. In both cases the recommendation is usually completely unqualified, with no warnings regarding connection state management.

(As an example, a search for "php mysql persistent connection" gave https://stackoverflow.com/questions/50303/persistent-db-connections-yea-or-nay as the 2nd result. Other than a link the persistent connections page mentioned below, there's not even a hint of state management in any of the answers given)

I just found there's a general page on persistent DB connections which does help to explain (some of) the issues (tho it's a bit of a wall of text), so I've added a link to that.

[AllenJB]

I just found there's a general page on persistent DB connections which does help to explain (some of) the issues (tho it's a bit of a wall of text), so I've added a link to that.

I've made some changes to this page to make it easier to read and make clearer the issues users should be aware of. I've added in a mention of connection pooling proxies, but I'm wary of mentioning specific tools as a) I lack experience with these and b) avoid recommending one specific tool over another - that should be up to the user to research and decide.

Any feedback is appreciated.

[kamil-tekiela]

I like your changes. They are very good, but I think the page needs more work after this. I'll try to think about this later.

[kamil-tekiela]

I'd remove this. Without a link or further explanation, we leave the user confused as to what it is and how to use it.

[AllenJB]

I think it's useful to make users aware these tools (with these capabilities) exist.

I don't think there's a necessity to link to specific tools - as I mentioned above I'm both inexperienced with these and want to avoid the manual appearing to recommend specific tools (which may then become unmaintained, or have better alternatives available).

(As someone who hangs out on various forums and chats, there are still have users picking up XAMPP, now 2 years after its last release, and I've been specifically told by at least 1 recently that it was because it was the first tool mentioned in the manual - and still is today!)

Also, the tools are going to be different depending on what database (and/or cloud provider) is used, so this would end up a list of different tools.

I think this provides just enough information to make users aware of these tools and give them the terms to search for them.

[adrian-enspired]

I would not simply remove this paragraph, especially since you're adding a "drawbacks" section.
the biggest issue i've seen with persistent connections is not people failing to clean up after themselves, but with how they behave more generally (i.e., the "one-to-one" concept mentioned here).

i've seen many beginners, or even experienced programmers that have little exposure to managing sapis/databases/etc., start using persistent connections without sufficient resources (e.g., in a cheap shared hosting environment) or without careful configuration (e.g., assuming you only need one persistent connection because it can be "shared"). in these cases, you're likely to see worse performance. this is actually the only thing i've ever had to explain to a programmer seeking help with persistent connections, and i've had to explain it quite a few times.

[AllenJB]

The problem I had with this paragraph (and this appears to me to be echoed by at least one user comment) is it reads to me as "you can simply enable persistent connections and not have to worry about making any other changes", which obviously isn't true, particularly in cases where PHP is not performing any additional management (eg. PDO MySQL).

Persistent connections can change behavior of scripts when cleanup is not performed.

The situation is not helped by apparent differences in behavior between different extensions. The cleanup performed by mysqli is just one manifestation.

Comparing https://github.com/php/php-src/blob/master/ext/pdo_mysql/tests/pdo_mysql_pconnect.phpt and https://github.com/php/php-src/blob/master/ext/mysqli/tests/mysqli_pconn_reuse.phpt shows PDO MySQL will happily reuse connections even if they are already in use by an existing PDO instance in the same process, while mysqli will not reuse connections until they're "closed". I haven't investigated whether it's required to explicitly close the connection or if this also happens if the mysqli object goes out of scope and is gc'd - I don't know whether there's a difference internally between these 2 actions when dealing with persistent connections.

I did have a quick check to see if there's similar tests that show how PDO PgSQL behaves, but couldn't see any, and I don't have a local postgres server running to perform my own tests. According to https://github.com/php/php-src/blob/master/ext/pgsql/tests/connection_reuse.phpt and https://github.com/php/php-src/blob/master/ext/pgsql/tests/gh13519.phpt both pg_connect and pg_pconnect will give you the same connection instance even if it's in active use by another PgSql\Connection object unless you explicitly request a new connection.

As far as I can see, "persistent connections were designed to be a one to one mapping to regular connections" is not (always) true (depending on the extension / database you're using) in any sense.

It's possible I am misunderstanding what "one-to-one mapping" is supposed to mean in this context, but I appear to not be the only one. Please feel free to submit suggestions for an alternative if you believe it's something not covered by the new version of this page, but I do not believe this paragraph should be restored.

[kamil-tekiela]

I think neither option is good. The previous paragraph was confusing, but the lack of it isn't good either. For now, we can remove it and we can add something better later.

[kamil-tekiela]

I still don't like this part. Are you saying that persistent connections should only be used with command-line scripts if they take a long time to execute? Also, doesn't this information belong in the next section?

[kamil-tekiela]

Suggested change

	Depending on your application and the database or extension you're using you
	may need to ensure that the state of connections is cleaned up before the
	script exits. Changes that may leave connections in an unexpected state
	include:
	Some database extensions perform automatic cleanup when the connection is reused;
	others leave this task at the discretion of the application developer.
	Depending on the chosen database extension and the application design,
	manual cleanup may be needed before the
	script exits. Changes that may leave connections in an unexpected state
	include: