<!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 and Connection management</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="pdo.constants.html">Predefined Constants</a></div>
<div class="next" style="text-align: right; float: right;"><a href="pdo.transactions.html">Transactions and auto-commit</a></div>
<div class="up"><a href="book.pdo.html">PDO</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="pdo.connections" class="chapter">
<h1>Connections and Connection management</h1>
<p class="para">
Connections are established by creating instances of the PDO base class.
It doesn't matter which driver you want to use; you always use the PDO
class name. The constructor accepts parameters for specifying the
database source (known as the DSN) and optionally for the username and
password (if any).
</p>
<p class="para">
<div class="example" id="example-899">
<p><strong>Example #1 Connecting to MySQL</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$dbh </span><span style="color: #007700">= new </span><span style="color: #0000BB">PDO</span><span style="color: #007700">(</span><span style="color: #DD0000">'mysql:host=localhost;dbname=test'</span><span style="color: #007700">, </span><span style="color: #0000BB">$user</span><span style="color: #007700">, </span><span style="color: #0000BB">$pass</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
If there are any connection errors, a <em>PDOException</em>
object will be thrown. You may catch the exception if you want to handle
the error condition, or you may opt to leave it for an application
global exception handler that you set up via
<span class="function"><a href="function.set-exception-handler.html" class="function">set_exception_handler()</a></span>.
</p>
<p class="para">
<div class="example" id="example-900"><p><strong>Example #2 Handling connection errors</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br /></span><span style="color: #007700">try {<br /> </span><span style="color: #0000BB">$dbh </span><span style="color: #007700">= new </span><span style="color: #0000BB">PDO</span><span style="color: #007700">(</span><span style="color: #DD0000">'mysql:host=localhost;dbname=test'</span><span style="color: #007700">, </span><span style="color: #0000BB">$user</span><span style="color: #007700">, </span><span style="color: #0000BB">$pass</span><span style="color: #007700">);<br /> foreach(</span><span style="color: #0000BB">$dbh</span><span style="color: #007700">-></span><span style="color: #0000BB">query</span><span style="color: #007700">(</span><span style="color: #DD0000">'SELECT * from FOO'</span><span style="color: #007700">) as </span><span style="color: #0000BB">$row</span><span style="color: #007700">) {<br /> </span><span style="color: #0000BB">print_r</span><span style="color: #007700">(</span><span style="color: #0000BB">$row</span><span style="color: #007700">);<br /> }<br /> </span><span style="color: #0000BB">$dbh </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br />} catch (</span><span style="color: #0000BB">PDOException $e</span><span style="color: #007700">) {<br /> print </span><span style="color: #DD0000">"Error!: " </span><span style="color: #007700">. </span><span style="color: #0000BB">$e</span><span style="color: #007700">-></span><span style="color: #0000BB">getMessage</span><span style="color: #007700">() . </span><span style="color: #DD0000">"<br/>"</span><span style="color: #007700">;<br /> die();<br />}<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<div class="warning"><strong class="warning">Warning</strong>
<p class="para">
If your application does not catch the exception thrown from the PDO
constructor, the default action taken by the zend engine is to terminate
the script and display a back trace. This back trace will likely reveal
the full database connection details, including the username and
password. It is your responsibility to catch this exception, either
explicitly (via a <em>catch</em> statement) or implicitly via
<span class="function"><a href="function.set-exception-handler.html" class="function">set_exception_handler()</a></span>.
</p>
</div>
<p class="para">
Upon successful connection to the database, an instance of the PDO class
is returned to your script. The connection remains active for the
lifetime of that PDO object. To close the connection, you need to
destroy the object by ensuring that all remaining references to it are
deleted--you do this by assigning <strong><code>NULL</code></strong> to the variable that holds the
object. If you don't do this explicitly, PHP will automatically close
the connection when your script ends.
</p>
<p class="para">
<div class="example" id="example-901">
<p><strong>Example #3 Closing a connection</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$dbh </span><span style="color: #007700">= new </span><span style="color: #0000BB">PDO</span><span style="color: #007700">(</span><span style="color: #DD0000">'mysql:host=localhost;dbname=test'</span><span style="color: #007700">, </span><span style="color: #0000BB">$user</span><span style="color: #007700">, </span><span style="color: #0000BB">$pass</span><span style="color: #007700">);<br /></span><span style="color: #FF8000">// use the connection here<br /><br /><br />// and now we're done; close it<br /></span><span style="color: #0000BB">$dbh </span><span style="color: #007700">= </span><span style="color: #0000BB">null</span><span style="color: #007700">;<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<p class="para">
Many web applications will benefit from making persistent connections to
database servers. Persistent connections are not closed at the end of the
script, but are cached and re-used when another script requests a
connection using the same credentials. The persistent connection cache
allows you to avoid the overhead of establishing a new connection every
time a script needs to talk to a database, resulting in a faster web
application.
</p>
<p class="para">
<div class="example" id="example-902">
<p><strong>Example #4 Persistent connections</strong></p>
<div class="example-contents">
<div class="phpcode"><code><span style="color: #000000">
<span style="color: #0000BB"><?php<br />$dbh </span><span style="color: #007700">= new </span><span style="color: #0000BB">PDO</span><span style="color: #007700">(</span><span style="color: #DD0000">'mysql:host=localhost;dbname=test'</span><span style="color: #007700">, </span><span style="color: #0000BB">$user</span><span style="color: #007700">, </span><span style="color: #0000BB">$pass</span><span style="color: #007700">, array(<br /> </span><span style="color: #0000BB">PDO</span><span style="color: #007700">::</span><span style="color: #0000BB">ATTR_PERSISTENT </span><span style="color: #007700">=> </span><span style="color: #0000BB">true<br /></span><span style="color: #007700">));<br /></span><span style="color: #0000BB">?></span>
</span>
</code></div>
</div>
</div>
</p>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If you wish to use persistent connections, you must set
<strong><code>PDO::ATTR_PERSISTENT</code></strong> in the array of driver options
passed to the PDO constructor. If setting this attribute with
<span class="function"><a href="pdo.setattribute.html" class="function">PDO::setAttribute()</a></span> after instantiation of the
object, the driver will not use persistent connections.
</p>
</p></blockquote>
<blockquote class="note"><p><strong class="note">Note</strong>:
<p class="para">
If you're using the PDO ODBC driver and your ODBC libraries support ODBC
Connection Pooling (unixODBC and Windows are two that do; there may be
more), then it's recommended that you don't use persistent PDO
connections, and instead leave the connection caching to the ODBC
Connection Pooling layer. The ODBC Connection Pool is shared with other
modules in the process; if PDO is told to cache the connection, then
that connection would never be returned to the ODBC connection pool,
resulting in additional connections being created to service those other
modules.
</p>
</p></blockquote>
</div>
<hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="pdo.constants.html">Predefined Constants</a></div>
<div class="next" style="text-align: right; float: right;"><a href="pdo.transactions.html">Transactions and auto-commit</a></div>
<div class="up"><a href="book.pdo.html">PDO</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
