diff --git a/features/persistent-connections.xml b/features/persistent-connections.xml index b6577d276017..3398ffa8209a 100644 --- a/features/persistent-connections.xml +++ b/features/persistent-connections.xml @@ -3,6 +3,8 @@ Persistent Database Connections + + What are Persistent Connections? Persistent connections are links that do not close when the execution of your script ends. When a persistent connection is @@ -24,12 +26,13 @@ functionality that wasn't possible with their non-persistent brothers. + + + + Web Requests - Why? - - - This has to do with the way web servers work. There are three ways - in which your web server can utilize PHP to generate web pages. + There are two ways in which your web server can utilize PHP to generate + web pages: The first method is to use PHP as a CGI "wrapper". When run this @@ -41,34 +44,37 @@ to use persistent connections -- they simply don't persist. - The second, and most popular, method is to run PHP as a module in a - multiprocess web server, which currently only includes Apache. A - multiprocess server typically has one process (the parent) which + The second, and most popular, method is to run PHP-FPM, or PHP as a module + in a multiprocess web server, which currently only includes Apache. + These setups typically have one process (the parent) which coordinates a set of processes (its children) who actually do the work of serving up web pages. When a request comes in from a client, it is handed off to one of the children that is not already serving another client. This means that when the same client makes a second request to the server, it may be served by a different - child process than the first time. When opening a persistent connection, - every following page requesting SQL services can reuse the same + child process than the first time. When opening a persistent connection, + every following page requesting SQL services can reuse the same established connection to the SQL server. + + + + Command-line Processes - The last method is to use PHP as a plug-in for a multithreaded web - server. Currently PHP has support for WSAPI, and NSAPI (on - Windows), which all allow PHP to be used as a plug-in on multithreaded - servers like Netscape FastTrack (iPlanet), Microsoft's Internet Information - Server (IIS), and O'Reilly's WebSite Pro. The behavior is essentially - the same as for the multiprocess model described before. - - - If persistent connections don't have any added functionality, what - are they good for? + As command-line PHP uses a new process for each script, persistent + connections are not shared between command-line scripts, so there is no + value in using them in transient scripts such as crons or commands. + However, they may be useful if, for example, you're writing a long-running + application server that serves many requests (or other connections) and each + may need their own database connection. + + + + Why Use Them? - The answer here is extremely simple -- efficiency. Persistent - connections are good if the overhead to create a link to your SQL - server is high. Whether or not this overhead is really high depends + Persistent connections are good if the overhead to create a link to your + SQL server is high. Whether or not this overhead is really high depends on many factors. Like, what kind of database it is, whether or not it sits on the same computer on which your web server sits, how loaded the machine the SQL server sits on is and so forth. The @@ -83,6 +89,10 @@ you'd have 20 different connections to the SQL server, one from each child. + + + + Potential Drawbacks: Connection Limits Note, however, that this can have some drawbacks if you are using a database with connection limits that are exceeded by persistent @@ -92,40 +102,61 @@ bugs in your scripts which do not allow the connections to shut down (such as infinite loops), the database with only 16 connections may be rapidly swamped. Check your database documentation for - information on handling abandoned or idle connections. + information on handling abandoned or idle connections (timeouts). - - - There are a couple of additional caveats to keep in mind when - using persistent connections. One is that when using table - locking on a persistent connection, if the script for whatever - reason cannot release the lock, then subsequent scripts using the - same connection will block indefinitely and may require that you - either restart the httpd server or the database server. Another is - that when using transactions, a transaction block will also carry - over to the next script which uses that connection if script execution - ends before the transaction block does. In either case, you can - use register_shutdown_function to register a - simple cleanup function to unlock your tables or roll back your - transactions. Better yet, avoid the problem entirely by not using - persistent connections in scripts which use table locks or - transactions (you can still use them elsewhere). - - + + + + Potential Drawbacks: Maintaining Connection State - An important summary. Persistent connections were designed to have - one-to-one mapping to regular connections. That means that you - should always be able to replace persistent - connections with non-persistent connections, and it won't change - the way your script behaves. It may (and - probably will) change the efficiency of the script, but not its - behavior! + 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: - - See also ibase_pconnect, ociplogon, - odbc_pconnect, oci_pconnect, - pfsockopen, and pg_pconnect. - + + Selected / default database + Table locks + Uncommitted transactions + Temporary tables + Connection specific settings or features such as profiling + + + Table locks and transactions that are not cleaned up or closed may cause + other queries to be blocked indefinitely and/or cause subsequent reuse of + the connection to cause unexpected changes. + + + Having the wrong database selected will cause subsequent reuse of the + connection to be unable to execute queries as expected (or execute them on + the wrong database if schemas are similar enough). + + + If temporary tables are not cleaned up, subsequent requests will not be able + to recreate the same table. + + + You can implement cleanup using class destructors or + register_shutdown_function. You may also want to + consider dedicated connection pooling proxies that include this as part of + their functionality. + + + + + &reftitle.seealso; + + + ibase_pconnect + oci_pconnect + odbc_pconnect + pfsockopen + pg_connect + MySQLi and Persistent Connections + PDO Connection Management + + +