Bug #52440 [Opn->Csd]: Add note for mysql/mysqli/pdo_mysql when using mysqlnd

Edit report at http://bugs.php.net/bug.php?id=52440&edit=1 ID: 52440 Updated by: kalle@php.net Reported by: anthon dot pang at gmail dot com Summary: Add note for mysql/mysqli/pdo_mysql when using mysqlnd -Status: Open +Status: Closed Type: Bug Package: Documentation problem Operating System: n/a PHP Version: 5.3.3 -Assigned To: +Assigned To: kalle Block user comment: N New Comment: This bug has been fixed in the documentation's XML sources. Since the online and downloadable versions of the documentation need some time to get updated, we would like to ask you to be a bit patient. Thank you for the report, and for helping us make our documentation better. Previous Comments: ------------------------------------------------------------------------ [2010-10-20 10:15:27] kalle@php.net Automatic comment from SVN on behalf of kalle Revision: http://svn.php.net/viewvc/?view=revision&revision=304545 Log: Fixed bug #52440 (Add note for mysql/mysqli/pdo_mysql when using mysqlnd) Documented PDO_MYSQL ini entries * pdo_mysql.default_socket * pdo_mysql.debug ------------------------------------------------------------------------ [2010-08-26 19:05:58] anthon dot pang at gmail dot com It's still a backward incompatibility when the same php.ini is used with php linked against libmysqlclient. Saying that this is how MySQL does it, isn't a convincing argument given the following. Reference: http://dev.mysql.com/doc/refman/5.0/en/connecting.html "The examples here use the mysql client program, but the principles apply to other clients such as mysqldump, mysqladmin, or mysqlshow." "On Unix, MySQL programs treat the host name localhost specially, in a way that is likely different from what you expect compared to other network-based programs." [ed. There is no requirement here for non-MySQL clients (eg php scripts) to follow MySQL's localhost semantics, which are noted as being unexpected/unconventional.] "For connections to localhost, MySQL programs attempt to connect to the local server by using a Unix socket file. This occurs even if a --port or -P option is given to specify a port number. To ensure that the client makes a TCP/IP connection to the local server, use --host or -h to specify a host name value of 127.0.0.1, or the IP address or name of the local server. You can also specify the connection protocol explicitly, even for localhost, by using the --protocol=TCP option. For example: shell> mysql --host=127.0.0.1 shell> mysql --protocol=TCP The --protocol option enables you to establish a particular type of connection even when the other options would normally default to some other protocol." [ed. To allow for the special case of "localhost", MySQL programs provide a "protocol" option.  This is absent from mysqlnd.  If MySQL semantics is a PHP requirement, then the mysqlnd implementation is incomplete.] "On Windows, you can force a MySQL client to use a named-pipe connection by specifying the --pipe or --protocol=PIPE option, or by specifying . (period) as the host name. If named-pipe connections are not enabled, an error occurs. Use the --socket option to specify the name of the pipe if you do not want to use the default pipe name." [ed. Ditto. http://bugs.php.net/bug.php?id=48082 ] ------------------------------------------------------------------------ [2010-08-26 10:21:11] uw@php.net As explained by Johannes in the other bug report http://bugs.php.net/52434 the hostname "localhost" has a special meaning for MySQL. Ever since "localhost" stands for "create a socket connection". The intend of "mysql:host=localhost;port=3307;dbname=testdb" is not "clearly to connect via TCP". That's simply wrong. "host=localhost" sets the rule "if you are on Unix, use a Unix domain socket to connect to MySQL". No bug here. The proposed Note must not be added to the documentation. What could be improved is the connection string example. As this bug report makes clear it has confused at least one user. This is something the docs folks can have a look at. The doc team may decide, for example, to link to some place which explains the special meaning of "localhost". ------------------------------------------------------------------------ [2010-07-25 20:47:17] anthon dot pang at gmail dot com Description: ------------ Since the one-line patch in #52434 was rejected, please add a 'Note' to document the following backwards incompatibility. First, the "more complete example" shown on this page http://www.php.net/manual/en/ref.pdo-mysql.connection.php : mysql:host=localhost;port=3307;dbname=testdb requires that a unix socket be configured in php.ini (even though the intent is clearly to connect via tcp) if php is built '--with-pdo-mysql=mysqlnd'. (This is a compat buster because the same DSN and php.ini works when php is instead linked against the mysql client libraries.) Second, this incompatibility also occurs when php is built '--with-mysqli=mysqlnd' (and presumably '--with-mysql=mysqlnd'). Thus, please add similar Notes to: http://www.php.net/manual/en/mysqli.connect.php http://ca2.php.net/mysqli_real_connect http://ca.php.net/mysql_connect Third, add comments to php.ini-development and php.ini-production files to clearly state that these *must* be configured when php is built with mysqlnd: pdo_mysql.default_socket = mysql.default_socket = mysqli.default_socket = (Though the configure script looks for and finds /var/run/mysqld/mysqld.sock, this information isn't used by mysqlnd.) ------------------------------------------------------------------------ -- Edit this bug report at http://bugs.php.net/bug.php?id=52440&edit=1