<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Connections</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqli.quickstart.dual-interface.html">Dual procedural and object-oriented interface</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqli.quickstart.statements.html">Executing statements</a></div>
<div class="up"><a href="mysqli.quickstart.html">Quick start guide</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="mysqli.quickstart.connections" class="section">
<h2 class="title">Connections</h2>
<p class="para">
The MySQL server supports the use of different transport
layers for connections. Connections use TCP/IP, Unix domain sockets or
Windows named pipes.
</p>
<p class="para">
The hostname <em>localhost</em> has a special meaning.
It is bound to the use of Unix domain sockets. It is not possible
to open a TCP/IP connection using the hostname <em>localhost</em>
you must use <em>127.0.0.1</em> instead.
</p>
<p class="para">
<div class="example" id="example-1621">
<p><strong>Example #1 Special meaning of localhost</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$mysqli </span><span style="color: #007700">= new </span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"localhost"</span><span style="color: #007700">, </span><span style="color: #DD0000">"user"</span><span style="color: #007700">, </span><span style="color: #DD0000">"password"</span><span style="color: #007700">, </span><span style="color: #DD0000">"database"</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">connect_errno</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"Failed to connect to MySQL: (" </span><span style="color: #007700">. </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">connect_errno </span><span style="color: #007700">. </span><span style="color: #DD0000">") " </span><span style="color: #007700">. </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">connect_error</span><span style="color: #007700">;<br />}<br />echo </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">host_info </span><span style="color: #007700">. </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /><br /></span><span style="color: #0000BB">$mysqli </span><span style="color: #007700">= new </span><span style="color: #0000BB">mysqli</span><span style="color: #007700">(</span><span style="color: #DD0000">"127.0.0.1"</span><span style="color: #007700">, </span><span style="color: #DD0000">"user"</span><span style="color: #007700">, </span><span style="color: #DD0000">"password"</span><span style="color: #007700">, </span><span style="color: #DD0000">"database"</span><span style="color: #007700">, </span><span style="color: #0000BB">3306</span><span style="color: #007700">);<br />if (</span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">connect_errno</span><span style="color: #007700">) {<br /> echo </span><span style="color: #DD0000">"Failed to connect to MySQL: (" </span><span style="color: #007700">. </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">connect_errno </span><span style="color: #007700">. </span><span style="color: #DD0000">") " </span><span style="color: #007700">. </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">connect_error</span><span style="color: #007700">;<br />}<br /><br />echo </span><span style="color: #0000BB">$mysqli</span><span style="color: #007700">-></span><span style="color: #0000BB">host_info </span><span style="color: #007700">. </span><span style="color: #DD0000">"\n"</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
<div class="example-contents"><p>The above example will output:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
Localhost via UNIX socket
127.0.0.1 via TCP/IP
</pre></div>
</div>
</div>
</p>
<p class="para">
<em class="emphasis">Connection parameter defaults</em>
</p>
<p class="para">
Depending on the connection function used, assorted parameters
can be omitted. If a parameter is not provided, then the extension attempts to
use the default values that are set in the PHP configuration file.
</p>
<p class="para">
<div class="example" id="example-1622">
<p><strong>Example #2 Setting defaults</strong></p>
<div class="example-contents">
<div class="inicode"><pre class="inicode">mysqli.default_host=192.168.2.27
mysqli.default_user=root
mysqli.default_pw=""
mysqli.default_port=3306
mysqli.default_socket=/tmp/mysql.sock</pre>
</div>
</div>
</div>
</p>
<p class="para">
The resulting parameter values are then passed to the client library
that is used by the extension. If the client library detects empty or unset
parameters, then it may default to the library built-in values.
</p>
<p class="para">
<em class="emphasis">Built-in connection library defaults</em>
</p>
<p class="para">
If the host value is unset or empty, then the client library will
default to a Unix socket connection on <em>localhost</em>.
If socket is unset or empty, and a Unix socket connection is requested,
then a connection to the default socket on <em>/tmp/mysql.sock</em>
is attempted.
</p>
<p class="para">
On Windows systems, the host name <em>.</em> is interpreted
by the client library as an attempt to open a Windows named pipe based
connection. In this case the socket parameter is interpreted as the pipe
name. If not given or empty, then the socket (pipe name) defaults to
<em>\\.\pipe\MySQL</em>.
</p>
<p class="para">
If neither a Unix domain socket based not a Windows named pipe based connection
is to be be established and the port parameter value is unset, the library
will default to port <em>3306</em>.
</p>
<p class="para">
The <a href="mysqlnd.overview.html" class="link">mysqlnd</a> library and the
MySQL Client Library (libmysqlclient) implement the same logic for determining defaults.
</p>
<p class="para">
<em class="emphasis">Connection options</em>
</p>
<p class="para">
Connection options are available to, for example, set
init commands which are executed upon connect, or for requesting use of
a certain charset. Connection options must be set before a network
connection is established.
</p>
<p class="para">
For setting a connection option, the connect operation has to be
performed in three steps: creating a connection handle with
<span class="function"><a href="mysqli.init.html" class="function">mysqli_init()</a></span>, setting the requested options using
<span class="function"><a href="mysqli.options.html" class="function">mysqli_options()</a></span>, and establishing the network
connection with <span class="function"><a href="mysqli.real-connect.html" class="function">mysqli_real_connect()</a></span>.
</p>
<p class="para">
<em class="emphasis">Connection pooling</em>
</p>
<p class="para">
The mysqli extension supports persistent database connections, which
are a special kind of pooled connections. By default, every database
connection opened by a script is either explicitly closed by the user during
runtime or released automatically at the end of the script. A persistent
connection is not. Instead it is put into a pool for later reuse, if
a connection to the same server using the same username, password, socket, port
and default database is opened. Reuse saves connection overhead.
</p>
<p class="para">
Every PHP process is using its own mysqli connection pool.
Depending on the web server deployment model, a PHP process may serve
one or multiple requests. Therefore, a pooled connection may be used
by one or more scripts subsequently.
</p>
<p class="para">
<em class="emphasis">Persistent connection</em>
</p>
<p class="para">
If a unused persistent connection for a given combination of host, username,
password, socket, port and default database can not be found in the connection pool,
then mysqli opens a new connection. The use of persistent connections can be
enabled and disabled using the PHP directive <a href="mysqli.configuration.html#ini.mysqli.allow-persistent" class="link">mysqli.allow_persistent</a>.
The total number of connections opened by a script can be limited with
<a href="mysqli.configuration.html#ini.mysqli.max-links" class="link">mysqli.max_links</a>. The maximum number of persistent connections
per PHP process can be restricted with <a href="mysqli.configuration.html#ini.mysqli.max-persistent" class="link">mysqli.max_persistent</a>.
Please note, that the web server may spawn many PHP processes.
</p>
<p class="para">
A common complain about persistent connections is that their state is
not reset before reuse. For example, open and unfinished transactions are not
automatically rolled back. But also, authorization changes which happened
in the time between putting the connection into the pool and reusing it
are not reflected. This may be seen as an unwanted side-effect. On the contrary,
the name <em>persistent</em> may be understood as a promise
that the state is persisted.
</p>
<p class="para">
The mysqli extension supports both interpretations of a persistent connection:
state persisted, and state reset before reuse. The default is reset.
Before a persistent connection is reused, the mysqli extension implicitly
calls <span class="function"><a href="mysqli.change-user.html" class="function">mysqli_change_user()</a></span> to reset the state. The
persistent connection appears to the user as if it was just opened. No
artifacts from previous usages are visible.
</p>
<p class="para">
The <span class="function"><a href="mysqli.change-user.html" class="function">mysqli_change_user()</a></span> function is an expensive operation.
For best performance, users may want to recompile the extension with the
compile flag <strong><code>MYSQLI_NO_CHANGE_USER_ON_PCONNECT</code></strong> being set.
</p>
<p class="para">
It is left to the user to choose between safe behavior and best performance.
Both are valid optimization goals. For ease of use, the safe behavior has
been made the default at the expense of maximum performance.
</p>
<p class="para">
<em class="emphasis">See also</em>
</p>
<p class="para">
<ul class="simplelist">
<li class="member"> <span class="methodname"><a href="mysqli.construct.html" class="methodname">mysqli::__construct()</a></span></li>
<li class="member"> <span class="methodname"><a href="mysqli.init.html" class="methodname">mysqli::init()</a></span></li>
<li class="member"> <span class="methodname"><a href="mysqli.options.html" class="methodname">mysqli::options()</a></span></li>
<li class="member"> <span class="methodname"><a href="mysqli.real-connect.html" class="methodname">mysqli::real_connect()</a></span></li>
<li class="member"> <span class="methodname"><a href="mysqli.change-user.html" class="methodname">mysqli::change_user()</a></span></li>
<li class="member"><a href="mysqli.get-host-info.html" class="link">$mysqli::host_info</a></li>
<li class="member"><a href="mysqli.configuration.html" class="link">MySQLi Configuration Options</a></li>
<li class="member"><a href="features.persistent-connections.html" class="link">Persistent Database Connections</a></li>
</ul>
</p>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="mysqli.quickstart.dual-interface.html">Dual procedural and object-oriented interface</a></div>
<div class="next" style="text-align: right; float: right;"><a href="mysqli.quickstart.statements.html">Executing statements</a></div>
<div class="up"><a href="mysqli.quickstart.html">Quick start guide</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
