====== PDO (new) ======
<WRAP important>
This is still [[https://github.com/ADOdb/ADOdb/pull/826|under development]]. 
Feedback is welcome, just add your comments in the pull request.
</WRAP>

~~NOTOC~~
<WRAP right box round 300px>
== 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>

===== Description =====

This driver supports connections using the standardized [[http://php.net/manual/en/book.pdo.php|PHP Data Objects]].This page refers to ADOdb release 5.23.0 and higher. For previous versions of ADOdb, see the [[v5:database:pdo|Previous Version Of This Page]].

Except for the ''pdo_odbc'' driver, all PDO drivers include support for full data dictionary functions (e.g. ''createTableSql()'',''addIndexSql()'', etc.)
-------------------------------------------------------
===== Quick Upgrade Notes ====
<WRAP info>
  * Instead of ''newAdoConnection('pdo')'', use ''newAdoConnection('pdo\driver')''
  * Passing a DSN statement to ''newAdoConnection()'' is no longer supported
  * Do not start the DSN statement with the driver name

</WRAP>
-------------------------------------------------------------
====Supported drivers====

^PHP Driver^Description^ADOdb Connector^
|pdo_firebird|Firebird|firebird|
|pdo_ibm|IBM DB2|ibm|
|pdo_informix|IBM Informix|informix|
|pdo_mysql|MySQL|mysql|
|pdo_oci|Oracle|oci|
|pdo_odbc|Generic ODBC|odbc|
|pdo_pgsql|Postgresql|pgsql|
|pdo_sqlite|SQLite|sqlite|
|pdo_sqlsrv|Microsoft SQL Server|sqlsrv|

====Unsupported Drivers====
  * pdo_mssql
  * pdo_dblib
  * pdo_cubrid
 
<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 PDO database type must be specified in the ''ADONewConnection()'' function call 
  - The **//DSN//** style of connection must be used in the ''connect()'' statement, e.g. to connect to a MySQL database:
<code php>
include_once 'adodb/adodb.inc.php';

$db = ADOnewConnection('pdo\mysql');

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

</code>

===== 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.
  * Unless otherwise described below, 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\firebird');

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

$dsnString= 'host=localhost;dbname=employee.fdb';
$db->connect($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 ====
==== Firebird ====
<WRAP right box round 300px>
== PDO Name ==
**pdo_firebird**
== Preferred Driver ==
[[v5:database:firebird|Firebird/Interbase Driver]]\\
</WRAP>

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

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

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

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

</code>
----------------------------------------------------------------
==== IBM DB2 ====
<WRAP right box round 300px>
== PDO Name ==
**pdo_ibm**
== Preferred Driver ==
[[v5:database:ibm_db2|DB2]]\\
</WRAP>

  * This driver requires the installation of the IBM DB2 client
  * See the [[v5:database:ibm_db2|Preferred Driver]] page for more information about building DSNs for use with DB2 connections.

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

$dsn = 'hostname=192.168.86.141;protocol=tcpip;port=25010;';
$dsn.= 'database=SAMPLE;uid=db2inst1;pwd=somepassword';
$user = '';
$password = ''

$db->connect($dsn,$user,$password);
</code>
------------------------------------------
==== IBM Informix ====
<WRAP right box round 300px>
== PDO Name ==
**pdo_informix**
</WRAP>

  * There is no native mode driver for IBM Informix Connections
  * This driver requires the installation of the IBM Informix Client
  * Supports Informix Databases version 12+

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

$dsn = 'hostname=192.168.86.141;service=ol_informix1410;database=stores_demo;';
$dsn.= 'server=ol_informix1410;protocol=onsoctcp;EnableScrollableCursors=1;';
$user = 'ix-user';
$password = 'ix-password'

$db->connect($dsn,$user,$password);
</code>
------------------------------------------
==== MySQL ====
<WRAP right box round 300px>
== PDO Name ==
**pdo_mysql**
== Preferred Driver ==
[[v5:database:mysql|mysqli]]\\
</WRAP>

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

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

$db->connect($dsn,$user,$password);
</code>
----------------------------------------------
==== ODBC====
<WRAP right box round 300px>
== PDO Name ==
**pdo_odbc**
</WRAP>
  * This is a simple driver for connection to any ODBC compliant database.
  * It is useful for reading and simple writes to data sources such as Microsoft Access, Excel and Google Sheets
  * There is no support for Data Dictionary functions or database specific items such as sequences. 

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

/*
* Points directly at the DSN configuration in Windows Control Panel
*/
$dsn  = 'MYDSN'

$db->connect($dsn);
</code>
----------------------------------------------
==== Oracle ====
<WRAP right box round 300px>
== PDO Name ==
**pdo_oci**
== Preferred Driver ==
[[v5:database:oracle|oci8]]\\

</WRAP>

  * There is no support for the complex binding features available in the Native Driver
  * This driver requires installation of an Oracle client, such as InstantClient

----------------------------------------
=== 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>
$db = newAdoConnection('pdo\oci');

//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="dbname=$tns";
$db->connect($dsnString,$userName,$password);

</code>
------------------------------------------
==== Postgres ====
<WRAP right box round 300px>
== PDO Name ==
pdo_pgsql
== Preferred Driver ==
[[v5:database:postgresql|postgres9]]\\
</WRAP>

---------------------------------------------------------------
=== Sample Connection String ===
<code php>
$db = newAdoConnection('pdo\pgsql');

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

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

-----------------------------------------------
==== SQLite ====
<WRAP right box round 300px>
== PDO Name ==
**pdo_sqlite**
== Preferred Driver ==
[[v5:database:sqlite]]\\
</WRAP>
----------------------------------------------------------------
=== Sample Connection String ===
<code php>
include 'adodb-dir/adodb.inc.php';
$db = ADOnewConnection('pdo\sqlite');

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

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

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

==== SQL Server ====
<WRAP right box round 300px>
== PDO Name ==
**pdo_sqlsrv**
== Preferred Driver ==
[[v5:database:microsoft_sql_server#mssqlnative|Native Mode Driver]]\\

</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
  * 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

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

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

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

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

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


{{tag>tier2}}