Edit Report a Bug

Conexões e gerenciamento de conexões

As conexões são estabelecidas criando instâncias da classe base PDO. Não importa qual driver você deseja usar; você sempre usa o nome da classe PDO. O construtor aceita parâmetros para especificar a fonte do banco de dados (conhecida como DSN) e opcionalmente para o nome de usuário e senha (se houver).

Exemplo #1 Conectando-se ao MySQL

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
?>

Se houver algum erro de conexão, um objeto PDOException será lançado. Você pode capturar a exceção se quiser lidar com a condição de erro, ou pode optar por deixá-la para um manipulador de exceção global do aplicativo que você configurou via set_exception_handler().

Exemplo #2 Tratando erros de conexão

<?php
try {
    $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
} catch (PDOException $e) {
    // tentar reconectar após algum intervalo, por exemplo
}

Aviso

Assim como qualquer outra exceção, PDOException pode ser capturada explicitamente, via uma instrução catch, ou implicitamente através de set_exception_handler(). Caso contrário, o comportamento padrão de converter uma exceção não capturada em um E_FATAL_ERROR ocorrerá. O erro fatal conterá uma rastreabilidade que pode vazar detalhes da conexão. Portanto, a opção php.ini display_errors deve ser definida como 0 em um servidor de produção.

Após a conexão bem-sucedida com o banco de dados, uma instância da classe PDO é retornada para seu script. A conexão permanece ativa pelo tempo de vida desse objeto PDO. Para fechar a conexão, você precisa destruir o objeto garantindo que todas as referências restantes a ele sejam deletadas - você faz isso atribuindo null à variável que mantém o objeto. Se você não fizer isso explicitamente, o PHP fechará automaticamente a conexão quando seu script terminar.

Nota: Se ainda houver outras referências a esta instância PDO (como de uma instância PDOStatement, ou de outras variáveis referenciando a mesma instância PDO), estas também devem ser removidas (por exemplo, atribuindo null à variável que referencia a instância PDOStatement).

Exemplo #3 Fechando uma conexão

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass);
// use a conexão aqui
$sth = $dbh->query('SELECT * FROM foo');

// e agora terminamos; feche-a
$sth = null;
$dbh = null;
?>

Muitas aplicações web se beneficiarão com a realização de conexões persistentes com servidores de banco de dados. As conexões persistentes não são fechadas no final do script, mas são armazenadas em cache e reutilizadas quando outro script solicita uma conexão usando as mesmas credenciais. O cache de conexão persistente permite evitar a sobrecarga de estabelecer uma nova conexão toda vez que um script precisa se comunicar com um banco de dados, resultando em uma aplicação web mais rápida.

Exemplo #4 Conexões persistentes

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(
    PDO::ATTR_PERSISTENT => true
));
?>

O valor da opção PDO::ATTR_PERSISTENT é convertido para bool (ativar/desativar conexões persistentes), a menos que seja uma string não numérica, caso em que permite usar vários pools de conexões persistentes. Isso é útil se diferentes conexões usam configurações incompatíveis, por exemplo, valores diferentes de PDO::MYSQL_ATTR_USE_BUFFERED_QUERY.

Nota:
Se desejar usar conexões persistentes, você deve definir PDO::ATTR_PERSISTENT no array de opções do driver passadas para o construtor PDO. Se definir este atributo com PDO::setAttribute() após a instanciação do objeto, o driver não usará conexões persistentes.

Nota:
Se estiver usando o driver PDO ODBC e suas bibliotecas ODBC suportarem Pool de Conexões ODBC (unixODBC e Windows são duas que suportam; pode haver mais), então é recomendável que você não use conexões PDO persistentes e, em vez disso, deixe o cache de conexão para a camada de Pool de Conexões ODBC. O Pool de Conexões ODBC é compartilhado com outros módulos no processo; se o PDO for instruído a armazenar em cache a conexão, então essa conexão nunca seria retornada ao pool de conexões ODBC, resultando em conexões adicionais sendo criadas para atender a esses outros módulos.

add a note

User Contributed Notes 13 notes

down

178

cappytoi at yahoo dot com ¶

10 years ago


Using PHP 5.4.26, pdo_pgsql with libpg 9.2.8 (self compiled). As usual PHP never explains some critical stuff in documentation. You shouldn't expect that your connection is closed when you set $dbh = null unless all you do is just instantiating PDO class. Try following:

<?php
$pdo = new PDO('pgsql:host=192.168.137.1;port=5432;dbname=anydb', 'anyuser', 'pw');
sleep(5);
$stmt = $pdo->prepare('SELECT * FROM sometable');
$stmt->execute();
$pdo = null;
sleep(60);
?>

Now check your database. And what a surprise! Your connection hangs for another 60 seconds. Now that might be expectable because you haven't cleared the resultset.

<?php
$pdo = new PDO('pgsql:host=192.168.137.160;port=5432;dbname=platin', 'cappytoi', '1111');
sleep(5);
$stmt = $pdo->prepare('SELECT * FROM admin');
$stmt->execute();
$stmt->closeCursor();
$pdo = null;
sleep(60);
?>

What teh heck you say at this point? Still same? Here is what you need to do to close that connection:

<?php
$pdo = new PDO('pgsql:host=192.168.137.160;port=5432;dbname=platin', 'cappytoi', '1111');
sleep(5);
$stmt = $pdo->prepare('SELECT * FROM admin');
$stmt->execute();
$stmt->closeCursor(); // this is not even required
$stmt = null; // doing this is mandatory for connection to get closed
$pdo = null;
sleep(60);
?>

PDO is just one of a kind because it saves you to depend on 3rd party abstraction layers. But it becomes annoying to see there is no implementation of a "disconnect" method even though there is a request for it for 2 years. Developers underestimate the requirement of such a method. First of all, doing $stmt = null  everywhere is annoying and what is most annoying is you cannot forcibly disconnect even when you set $pdo = null. It might get cleared on script's termination but this is not always possible because script termination may delayed due to slow client connection etc.

Anyway here is how to disconnect forcibly using postgresql:

<?php
$pdo = new PDO('pgsql:host=192.168.137.160;port=5432;dbname=platin', 'cappytoi', '1111');
sleep(5);
$stmt = $pdo->prepare('SELECT * FROM admin');
$stmt->execute();
$pdo->query('SELECT pg_terminate_backend(pg_backend_pid());');
$pdo = null;
sleep(60);
?>

Following may be used for MYSQL: (not guaranteed)
KILL CONNECTION_ID()

down

d dot bergloev at gmail dot com ¶

8 years ago


I would please advice people who talk about database port in reference with socket files to please read up about what a socket file is. TCP/IP uses ports, a socket file however is a direct pipe line to your database. So no, you should not replace localhost with local ip if you use a different port on your database server, because the socket file has nothing to do with your TCP/IP setup. And whenever possible, using the local socket file is much faster than establishing new TCP/IP connections on each request which is only meant for remote database servers.

down

jak dot spalding at gmail dot com ¶

13 years ago


Just thought I'd add in and give an explanation as to why you need to use 127.0.0.1 if you have a different port number.

The mysql libraries will automatically use Unix sockets if the host of "localhost" is used. To force TCP/IP you need to set an IP address.

down

ogierschelvis at gmail dot com ¶

9 years ago


As http://stackoverflow.com/questions/17630772/pdo-cannot-connect-remote-mysql-server points out; sometimes when you want to connect to an external server like this:

<?php
$conn = new PDO('mysql:host=123.4.5.6;dbname=test_db;port=3306','username','password');
?>

it will fail no matter what. However if you put a space between mysql: and host like this:

<?php
$conn = new PDO('mysql: host=123.4.5.6;dbname=test_db;port=3306','username','password');
?>

it will magically work. I'm not sure if this applies in all cases or server setups. But I think it's worth mentioning in the docs.

down

Moshe Dolev ¶

6 years ago


Please note that you cannot use persistent connections to create temporary tables in mysql/mariadb.
Tables you create using a statement like "create temporary table TABLE1 ..." are destroyed only when the mysql session ends (not php session !). This never happens if you use a persistent connection. 
If you create a temporary table on a persistent connection, the table will live even after the php script ends. The next php script that will try to issue the same create temporary table statement, will receive an error.
IMHO, this fact makes persistent connections quite useless.

down

neville at whitespacers dot com ¶

15 years ago


To avoid exposing your connection details should you fail to remember to catch any exception thrown by the PDO constructor you can use the following class to implicitly change the exception handler temporarily.

<?php

Class SafePDO extends PDO {
 
        public static function exception_handler($exception) {
            // Output the exception details
            die('Uncaught exception: ', $exception->getMessage());
        }
 
        public function __construct($dsn, $username='', $password='', $driver_options=array()) {

            // Temporarily change the PHP exception handler while we . . .
            set_exception_handler(array(__CLASS__, 'exception_handler'));

            // . . . create a PDO object
            parent::__construct($dsn, $username, $password, $driver_options);

            // Change the exception handler back to whatever it was before
            restore_exception_handler();
        }

}

// Connect to the database with defined constants
$dbh = new SafePDO(PDO_DSN, PDO_USER, PDO_PASSWORD);

?>

down

dan dot franklin at pearson dot com ¶

16 years ago


Note that you can specify a port number with "port=####", but this port number will be ignored if the host is localhost.  If you want to connect to a local port other than the default, use host=127.0.0.1 instead of localhost.

down

edsanhu at gmail dot com ¶

9 years ago


For being able to retrieve information from the db in utf-8 the connection assignment has to add to the dsn `charset=utf8`:

<?php
$dbh = new PDO('mysql:host=localhost;dbname=test;charset=utf8', $user, $pass);
?>

down

antony at harrisretail dot co dot uk ¶

4 years ago


It's not possible to use a persistent connection and to extend the PDOStatement class to add methods to the standard class. This means that you cannot do:

 <?php
  $dbh = new PDO('mysql:host=localhost;dbname=test', $user, $pass, array(PDO::ATTR_PERSISTENT => true));
  $dbh->setAttribute(PDO::ATTR_STATEMENT_CLASS, array('MyPDOStatement', array($this)));
?>

This results in an error:

Fatal error: Uncaught exception 'PDOException' with message 'SQLSTATE[HY000]: General error: PDO::ATTR_STATEMENT_CLASS cannot be used with persistent PDO instances

down

thz at plista dot com ¶

11 years ago


If you are using PHP 5.4 and later, you can no longer use persistent connections when you have your own database class that derives from the native PDO object. If you do, you will get segmentation faults during the PHP process shutdown.

Please see this bug report for more information: https://bugs.php.net/bug.php?id=63176

down

-3

me+nospam at tati dot pro ¶

8 years ago


If you want to keep connection after fork exit, you can kill with SIGKILL forked process.

<?php
$dbh = new PDO('pgsql:host=localhost;dbname=test', $user, $pass);
$pid = pcntl_fork();
if($pid == 0){
        // forked process 'll exit immediately
        exit;
}
sleep(1);
$statement = $dbh->query('select 1');
var_dump($statement);
?>
Result: false

<?php
$dbh = new PDO('pgsql:host=localhost;dbname=test', $user, $pass);
$pid = pcntl_fork();
if($pid == 0){
        // use sigkill to close process
        register_shutdown_function(function(){
                posix_kill(getmypid(), SIGKILL);
        });
        // forked process 'll exit immediately
        exit;
}
sleep(1);
$statement = $dbh->query('select 1');
var_dump($statement);
?>
Result: object(PDOStatement)#3 (1) {
  ["queryString"]=>
  string(8) "select 1"
}

down

-5

alvaro at demogracia dot com ¶

13 years ago


On connection errors, the PDO constructor seems to do two things no matter your PDO::ATTR_ERRMODE setting:

1. Trigger a warning
2. Throw a PDOException

If you set the PDO::ATTR_ERRMODE parameter, it will only take effect on further operations.

down

-63

paulo dot sistema at gmail dot com ¶

7 years ago


Hello guys!
Has anyone used the ORACLE WALLET feature in PHP or Java?

https://docs.oracle.com/middleware/1213/wls/JDBCA/oraclewallet.htm#JDBCA596

I would like to know how to implement it because I can not implement. We use PDO + PHP in all applications and now there is this demand of the DBA.

Thank you

add a note