DSN – The Data Source Name


To connect to a database through PEAR::MDB2, you have to create a valid DSN - data source name. This DSN consists in the following parts:

  • phptype: Database backend used in PHP (i.e. mysql , pgsql etc.)
  • dbsyntax: Database used with regards to SQL syntax etc.
  • protocol: Communication protocol to use ( i.e. tcp, unix etc.)
  • hostspec: Host specification (hostname[:port])
  • database: Database to use on the DBMS server
  • username: User name for login
  • password: Password for login
  • proto_opts: Maybe used with protocol
  • option: Additional connection options in URI query string format. options get separated by &. The Following table shows a non complete list of options:
List of options
Name Description Type
charset Some backends support setting the client charset. (Invokes setCharset(string $charset, [resource $connection = null]) string
new_link [boolean] Some RDBMS do not create new connections when connecting to the same host multiple times. If this option is set to TRUE it will attempt to force a new connection. boolean

The DSN can either be provided as an associative array or as a string. The array format is preferred, since it doesn't require a further parsing step (see the Connecting chapter for an example). The string format of the supplied DSN is in its fullest form:


Most variations are allowed:


The currently supported database backends are:

fbsql  -> FrontBase
ibase  -> InterBase / Firebird (requires PHP 5)
mssql  -> Microsoft SQL Server (NOT for Sybase. Compile PHP --with-mssql)
mysql  -> MySQL
mysqli -> MySQL (supports new authentication protocol) (requires PHP 5)
oci8   -> Oracle 7/8/9/10
pgsql  -> PostgreSQL
querysim -> QuerySim
sqlite -> SQLite 2

A second DSN format is supported


If your database, option values, username or password contain characters used to delineate DSN parts, you can escape them via URI hex encodings:

: = %3a   / = %2f   @ = %40
+ = %2b   ( = %28   ) = %29
? = %3f   = = %3d   & = %26

Please note, that some features may be not supported by all database backends.


Connect to database through a socket


Connect to database on a non standard port


Connect to SQLite on a Unix machine using options


Connect to SQLite on a Windows machine using options


Connect to MySQLi using SSL


Connect to Oracle using Service name


Connect to Oracle using "Easy Connect" syntax

A feature overview (Previous) Connecting and disconnecting a database (Next)
Last updated: Sat, 16 Feb 2019 — Download Documentation
Do you think that something on this page is wrong? Please file a bug report.
View this page in:
  • English

User Notes:

Note by: jay@widernet.org
When using an array for the dsn, additional options must be added as individual elements.

This is wrong:
$dsn = array(
'options' => 'charset=utf8&newlink=true'

This is correct:
$dsn = array(
'charset' => 'utf8',
'newlink' => 'true
Note by: tim@vanillaforums.com

If your protocol is 'unix' and you're using array syntax, you need to specify a 'socket' parameter (which isn't documented here) in order to tell it where to connect.
Note by: mapopa@gmail.com
if you are using firebird on linux then you need to add an extra slash to the db path like this

$mdb2 =& MDB2::connect(’ibase://sysdba:masterkey@localhost//var/lib/firebird/2.1/data/employee.fdb’);

and you can check the result with the extra debug info

if (PEAR::isError($mdb2)) {
die($mdb2->getMessage(). ‘,’ . $mdb2->getDebugInfo());
Note by: nilya
If you use Firebird database, specify dbsyntax='firebird'.
For example, "ibase(firebird)://SYSDBA:masterkey@localhost/dbname".

In current version (MDB2_Driver_ibase 1.4.1) this value affects only limiting queries (by setLimit(limit,offset))