PEAR Manual
Prev |  | Next

# Introduction - DSN

Introduction - DSN -- The Data Source Name

## Description

To connect to a database through PEAR::DB, 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` , `odbc` etc.)
`dbsyntax`: Database used with regards to SQL syntax etc. When using ODBC as the `phptype`, set this to the DBMS type the ODBC driver is connecting to. Examples: `access`, `db2`, `mssql`, `navision`, `solid`, 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 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:

    dbase  -> dBase
    fbsql  -> FrontBase (functional since DB 1.7.0)
    ibase  -> InterBase (functional since DB 1.7.0)
    ifx    -> Informix
    msql   -> Mini SQL (functional since DB 1.7.0)
    mssql  -> Microsoft SQL Server (NOT for Sybase. Compile PHP --with-mssql)
    mysql  -> MySQL (for MySQL <= 4.0)
    mysqli -> MySQL (for MySQL >= 4.1) (requires PHP 5) (since DB 1.6.3)
    oci8   -> Oracle 7/8/9
    odbc   -> ODBC (Open Database Connectivity)
    pgsql  -> PostgreSQL
    sqlite -> SQLite
    sybase -> Sybase

With an up-to-date version of DB, you can use a second DSN format

    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. Please refer to the PEAR DB extensions status document located at: ``/pear/base/dir`/DB/doc/STATUS` to get a detailed list about what features are supported by which backend.

## Example

Example 33-1. Connect to database through a socket
    mysql://user@unix(/path/to/socket)/pear

Example 33-2. Connect to database on a non standard port
    pgsql://user:pass@tcp(localhost:5555)/pear

Example 33-3. Connect to SQLite on a Unix machine using options
    sqlite:////full/unix/path/to/file.db?mode=0666

Example 33-4. Connect to SQLite on a Windows machine using options
    sqlite:///c:/full/windows/path/to/file.db?mode=0666

Example 33-5. Connect to MySQLi using SSL
    mysqli://user:pass@localhost/pear?key=client-key.pem&cert=client-cert.pem

Example 33-6. Connecting to MS Access sometimes requires `admin` as the user name
    odbc(access)://admin@/datasourcename

Example 33-7. Connecting to ODBC with a specific cursor
    odbc(access)://admin@/datasourcename?cursor=SQL_CUR_USE_ODBC

Prev | Home | Next
DB | Up | Introduction - Connect