++++ Introduction

Doctrine_Connection is a wrapper for database connection. It handles several things: 

*  Handles database portability things missing from PDO (eg. {{LIMIT}} / {{OFFSET}} emulation)
*  Keeps track of {{Doctrine_Table}} objects
*  Keeps track of records
*  Keeps track of records that need to be updated / inserted / deleted
*  Handles transactions and transaction nesting
*  Handles the actual querying of the database in the case of {{INSERT}} / {{UPDATE}} / {{DELETE}} operations
*  Can query the database using the DQL API (see {{Doctrine_Query}})
*  Optionally validates transactions using {{Doctrine_Validator}} and gives full information of possible errors.


++++ Available drivers

Doctrine has drivers for every PDO-supported database. The supported databases are:

* FreeTDS / Microsoft SQL Server / Sybase
* Firebird/Interbase 6
* Informix
* Mysql
* Oracle
* Odbc
* PostgreSQL
* Sqlite


++++ Getting a table object

In order to get table object for specified record just call {{Doctrine_Record::getTable()}} or {{Doctrine_Connection::getTable()}}.

<code type="php">
$manager = Doctrine_Manager::getInstance();

// open new connection

$conn = $manager->openConnection(new PDO('dsn','username','password'));

// getting a table object

$table = $conn->getTable('User');
</code>


++++ Flushing the connection

Creating new record (database row) is very easy. You can either use the {{Doctrine_Connection::create()}} or {{Doctrine_Table::create()}} method to do this or just simply use the new operator.

<code type="php">
$user = new User();
$user->name = 'Jack';

$group = $conn->create('Group');
$group->name = 'Drinking Club';

// saves all the changed objects into database

$conn->flush();
</code>


++++ Querying the database

{{Doctrine_Connection::query()}} is a simple method for efficient object retrieval. It takes one parameter (DQL query) and optionally prepared statement params.

<code type="php">

// select all users

$users = $conn->query('FROM User');

// select all users where user email is jackdaniels@drinkmore.info

$users = $conn->query("FROM User WHERE User.Email.address = 'jackdaniels@drinkmore.info'");

// using prepared statements

$users = $conn->query('FROM User WHERE User.name = ?', array('Jack'));
</code>


++++ Getting connection state

Connection state gives you information about how active connection currently is. You can get the current state by calling {{Doctrine_Connection::getState()}}.

<code type="php">
switch($conn->getState()):
    case Doctrine_Connection::STATE_ACTIVE:
        // connection open and zero open transactions
    break;
    case Doctrine_Connection::STATE_ACTIVE:
        // one open transaction
    break;
    case Doctrine_Connection::STATE_BUSY:
        // multiple open transactions
    break;
    case Doctrine_Connection::STATE_CLOSED:
        // connection closed
    break;
endswitch;
</code>