====== PDO ======
~~NOTOC~~

===== Description =====

This driver supports connections using the standardized [[http://php.net/manual/en/book.pdo.php|PHP Data Objects]]. 

Supported drivers:

^PHP Driver^Description^ADOdb Connector^
|pdo_firebird|Firebird|firebird|
|pdo_mssql|SQL Server with FREETDS|mssql|
|pdo_mysql|MySQL|mysql|
|pdo_oci|Oracle|oci|
|pdo_pgsql|Postgresql|pgsql|
|pdo_sqlite|SQLite|sqlite|
|pdo_sqlsrv|SQL Server using Windows Native Client|sqlsrv|
 
<WRAP important>
Note that the //pdo// driver cannot be used on its own. It is a technical component that is used internally by the above drivers. 
</WRAP>


===== Establishing A Connection =====
To establish a connection, the **//DSN//** style of connection must be used, the first argument of the DSN string being the database type, e.g. to connect to a MySQL database:
<code php>
include_once 'adodb/adodb.inc.php';
$db = ADOnewConnection('pdo');

$user     = 'pdo-user';
$password = 'pdo-pass';
$dsnString= 'host=localhost;dbname=employees;charset=utf8mb4';
$db->connect('mysql:' . $dsnString,$user,$password);

</code>

Note that in the above example, the database type is separated from the rest of the DSN string by a : (colon). The rest of the DSN arguments are separated by a ; (semi-colon).


===== Preferred Drivers =====

Using ADOdb effectively eliminates the need to use the PHP PDO driver as it hides the PHP level command:

  * It provides true database abstraction, for example, the ADOdb method ''selectLimit()'' provides a true abstraction of the row limiting and offset of all databases. With PDO, you still need to provide the database specific syntax.
  * In all cases, using native drivers (listed below) provide better functionality, as well as performance, than the equivalent PDO driver. This is true at both the ADOdb and PHP level


===== Setting Construction Parameters =====
Certain attributes need to be passed to the [[https://www.php.net/manual/en/pdo.construct.php|PDO Constructor]], for example, changing the error mode. To facilitate this, a PDO specific settable array **'' ADOConnection::pdoParameters ''** is provided:

<code php>
$db = newAdoConnection('pdo');

$db->pdoParameters = [
\PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION
];

$dsnString= 'host=localhost;dbname=employee.fdb';
$db->connect('firebird:' . $dsnString,"SYSDBA", "password");

</code>

===== The PDO setAttribute function =====
For parameters that are set after the class is instantiated, The PDO::setAttribute() method can be populated using [[v5:reference:connection:setconnectionparameter|setConnectionParameter()]].

===== Individual Driver Status ====
-----------------------
==== pdo_mssql ====
<WRAP right box round 300px>
== Preferred Driver ==
[[v5:database:microsoft_sql_server#mssqlnative|Microsoft native mode driver For Linux]]\\
[[v5:database:microsoft_sql_server#mssql|FreeTDS Driver For Unix]]\\
== Specification ==
^Driver Name|pdo|
^Data Provider|pdo|
^Status|Inactive((This driver is not supported by ADOdb project members, but you can contribute to this driver if you have the expertise))|
^Windows|No|
^Unix|Yes|
^ADOdb V5|Yes|
^ADOdb V6|Yes|
</WRAP>
The current status of this driver is unknown. Consider using the [[v5:database:pdo#pdo_sqlsrv|mssqlnative]] driver instead.
------------------------------------------
==== pdo_mysql ====
<WRAP right box round 300px>
== Preferred Driver ==
[[v5:database:mysql|mysqli]]\\
== Specification ==
^Driver Name|pdo|
^Data Provider|pdo|
^Status|Active((This driver is supported by ADOdb project members))|
^Windows|Yes|
^Unix|No|
^ADOdb V5|Yes|
^ADOdb V6|Yes|
</WRAP>

  * Some **//Meta//** functions are unavailable


-------------------------------------------------------
=== Sample Connection String ===
<code php>
include 'adodb-dir/adodb.inc.php';
$db   = ADOnewConnection('pdo');

$dsn  = 'mysql:hostname=127.0.0.1;database=employees;'
$user = 'user';
$password = 'password'

$db->connect($dsn,$user,$password);
</code>
----------------------------------------------
==== pdo_oci ====
<WRAP right box round 300px>
== Preferred Driver ==
[[v5:database:oracle|oci8]]\\
== Specification ==
^Driver Name|pdo|
^Data Provider|pdo|
^Status|Active((This driver is supported by ADOdb project members))|
^Windows|Yes|
^Unix|Yes|
^ADOdb V5|Yes|
^ADOdb V6|Yes|
</WRAP>
== Limitations ==


  * There is no support for the complex binding features available in the Native Driver
  * Some MetaFunctions are unavailable

----------------------------------------
=== Sample Connection String ===
If you are using the instantclient, and there is no tsnames.ora defined, you can define a connection like this
<code php>

//Connecting to Oracle Express on 192.168.86.86
$tns = " 
(DESCRIPTION =
    (ADDRESS_LIST =
      (ADDRESS = (PROTOCOL = TCP)(HOST = 192.168.86.86)(PORT = 1521))
    )
    (CONNECT_DATA =
      (SERVICE_NAME = XEPDB1)
    )
  )
";
$dsnString="oci:dbname=$tns";
$db->connect($dsnString,$userName,$password);

</code>
------------------------------------------
==== pdo_pgsql ====
<WRAP right box round 300px>
== Preferred Driver ==
[[v5:database:postgresql|postgres9]]\\
== Specification ==
^Driver Name|pdo|
^Data Provider|pdo|
^Status|Active((This driver is supported by ADOdb project members))|
^Windows|Yes|
^Unix|Yes|
^ADOdb V5|Yes|
^ADOdb V6|Yes|
</WRAP>
=== Status ===
Some features are not supported
---------------------------------------------------------------
=== Sample Connection String ===
<code php>
$db = newAdoConnection('pdo');

$dsn  = 'pgsql:host=192.168.0.212;dbname=dvdrental';
$user = 'someuser';
$pass = 'somepass';

$db->connect($dsn,$user,$pass);
</code>

-----------------------------------------------
==== pdo_sqlite ====
<WRAP right box round 300px>
== Preferred Driver ==
[[v5:database:sqlite]]\\
== Specification ==
^Driver Name|pdo|
^Data Provider|pdo|
^Status|Active((This driver is supported by ADOdb project members))|
^Windows|Yes|
^Unix|No|
^ADOdb V5|Yes|
^ADOdb V6|Yes|
</WRAP>
----------------------------------------------------------------
=== Sample Connection String ===
<code php>
include 'adodb-dir/adodb.inc.php';
$db = ADOnewConnection('pdo');

$dsn  = 'sqlite:/home/sqlite/adodb-sqlite.db';
$user = 'root';

$db->connect($dsn,$user);
</code>

-------------------------------------------------

==== pdo_sqlsrv ====
<WRAP right box round 300px>
== Preferred Driver ==
[[v5:database:microsoft_sql_server#mssqlnative|Native Mode Driver]]\\
== Specification ==
^Driver Name|pdo|
^Data Provider|pdo|
^Status|Active((This driver is supported by ADOdb project members))|
^Windows|Yes|
^Unix|Yes|
^ADOdb V5|Yes|
^ADOdb V6|Yes|


</WRAP>
  * This driver requires the installation of the Microsoft native client library, as well as the [[https://www.microsoft.com/en-us/download/details.aspx?id=20098|Microsoft SQL Server PDO drivers for PHP]]
  * Dates are always returned as strings
  * Most //**Meta**// functions are unsupported
  * [[v5:reference:connection:setconnectionparameter|setConnectionParameter()]] is not supported
  * This driver can also be used on Linux platforms, beginning with PHP Version 7. The program relies on the Microsoft drivers for Linux. For more information, see the [[v5:database:microsoft_sql_server|mssqlnative driver]]
  * You cannot change the character set in the driver. This is a limitation of the PDO driver, not ADOdb
  * No support for parameter binding

----------------------------------------------------------------------------

=== Sample Connection String ===
<code php>
include 'adodb-dir/adodb.inc.php';
$db = ADOnewConnection('pdo');

$user = 'user';
$pass = 'password';
$dsn  ='sqlsrv:server=SERVER\SQLEXPRESS;database=NORTHWND;';

$db->connect($dsn,$user,$password);
</code>

-----------------------------------------------------------------------------

==== pdo_firebird ====
<WRAP right box round 300px>
== Native Driver ==
[[v5:database:firebird|Firebird/Interbase Driver]]\\
== Specification ==
^Driver Name|pdo|
^Data Provider|pdo|
^Status|Active((This driver is supported by ADOdb project members))|
^Windows|Yes|
^Unix|Yes|
^ADOdb V5|Yes|
^ADOdb V6|Yes|
</WRAP>
Unlike other pdo drivers, pdo_firebird is the preferred driver for this database. This is due to specific issues with this driver reported [[https://bugs.php.net/bug.php?id=72175|here]]. 

------------------------------------------------------------
=== Sample Connection String ===

<code php>
include 'adodb-dir/adodb.inc.php';
$db = ADOnewConnection('pdo');

$dsn  = 'firebird:dbname=employee.fdb;hostname=localhost';
$user = 'SYSDBA';
$pass = 'master-key';

$db->connect($dsn,$user,$pass);

</code>

{{tag>tier2}}