Introduction - DSN

Introduction - DSN -- The Data Source Name

Description

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:

Table 33-1. List of options

NameDescription
charset Some backends support setting the client charset.
new_link Some RDBMS do not create new connections when connecting to the same host multiple times. This option will attempt to force a new connection.

The DSN can either be provided as an associative array or as a string. The string format of the supplied DSN is in its fullest form:
phptype(dbsyntax)://username:password@protocol+hostspec/database?option=value

Most variations are allowed:
phptype://username:password@protocol+hostspec:110//usr/db_file.db
phptype://username:password@hostspec/database
phptype://username:password@hostspec
phptype://username@hostspec
phptype://hostspec/database
phptype://hostspec
phptype:///database
phptype:///database?option=value&anotheroption=anothervalue
phptype(dbsyntax)
phptype

The currently supported database backends are:
fbsql  -> FrontBase
ibase  -> InterBase (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
pgsql  -> PostgreSQL
querysim -> QuerySim
sqlite -> SQLite

A second DSN format is supported
phptype(syntax)://user:pass@protocol(proto_opts)/database

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

Warning

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

Example