PEAR Manual
Prev |  | Next

# Introduction - Connect

Introduction - Connect -- Connecting and disconnecting a database

## Description

To connect to a database you have to use the function connect(), which requires a valid DSN as the first parameter. This parameter can either be a string or an array. If using an array, the array used gets merged with the default information:

    $dsn = array(
        'phptype'  => false,
        'dbsyntax' => false,
        'username' => false,
        'password' => false,
        'protocol' => false,
        'hostspec' => false,
        'port'     => false,
        'socket'   => false,
        'database' => false,
    );

Any elements you set override the defaults and the remainder stay at their defaults.

The second parameter is the optional `$options` array that can contain runtime configuration settings for this package. See setOption() for more information on the available settings.

In case of success you get a new instance of the database class. It is strongly recommened to check this return value with isError().

To disconnect use the method disconnect() from your database class instance.

Example 33-1. Connect and disconnect
    <?php
    require_once 'DB.php';

    $dsn = 'pgsql://someuser:apasswd@localhost/thedb';
    $options = array(
        'debug'       => 2,
        'portability' => DB_PORTABILITY_ALL,
    );

    $db =& DB::connect($dsn, $options);
    if (PEAR::isError($db)) {
        die($db->getMessage());
    }

    // ...

    $db->disconnect();
    ?>

Example 33-2. Connect using an array for the DSN information
    <?php
    require_once 'DB.php';

    $dsn = array(
        'phptype'  => 'pgsql',
        'username' => 'someuser',
        'password' => 'apasswd',
        'hostspec' => 'localhost',
        'database' => 'thedb',
    );

    $options = array(
        'debug'       => 2,
        'portability' => DB_PORTABILITY_ALL,
    );

    $db =& DB::connect($dsn, $options);
    if (PEAR::isError($db)) {
        die($db->getMessage());
    }
    ?>
When connecting to SQLite using a DSN array, the value of the `mode` element must be a string:
    <?php
    $dsn = array(
        'phptype'  => 'sqlite',
        'database' => 'thedb',
        'mode'     => '0644',
    );
    ?>

Example 33-3. Connect to MySQLi via SSL using an array for the DSN information The `ssl` element of the `$options` array must be set to `TRUE` in order for SSL to work. Each of the extra elements in the `$dsn` array (`key` through `cipher` in the example below) are optional.
    <?php
    require_once 'DB.php';

    $dsn = array(
        'phptype'  => 'mysqli',
        'username' => 'someuser',
        'password' => 'apasswd',
        'hostspec' => 'localhost',
        'database' => 'thedb',
        'key'      => 'client-key.pem',
        'cert'     => 'client-cert.pem',
        'ca'       => 'cacert.pem',
        'capath'   => '/path/to/ca/dir',
        'cipher'   => 'AES',
    );

    $options = array(
        'ssl' => true,
    );

    $db =& DB::connect($dsn, $options);
    if (PEAR::isError($db)) {
        die($db->getMessage());
    }
    ?>

Example 33-4. Connect to a PostgreSQL database via a socket
    <?php
    require_once 'DB.php';

    $dsn = 'pgsql://someuser:apasswd@unix(/tmp)/thedb';
    $options = array(
        'debug'       => 2,
        'portability' => DB_PORTABILITY_ALL,
    );

    $db =& DB::connect($dsn, $options);
    if (PEAR::isError($db)) {
        die($db->getMessage());
    }
    ?>

## See

DB_Error, setOption(), "Intro - Portability"

Prev | Home | Next
Introduction - DSN | Up | Introduction - Query