diff --git a/manual/docbook/book/conn-mgt.xml b/manual/docbook/book/conn-mgt.xml index 667d71619..02a9be477 100644 --- a/manual/docbook/book/conn-mgt.xml +++ b/manual/docbook/book/conn-mgt.xml @@ -188,4 +188,186 @@ phptype(dbsyntax)://username:password@protocol+hostspec/database?option=value + + Opening a new connection + + + Opening a new database connection in Doctrine is very easy. If you wish + to use PDO (www.php.net/PDO) + you can just initalize a new PDO object: + + + getMessage(); + } +?>]]> + + + If your database extension isn't supported by PDO you can use special + Doctrine_Adapter class (if availible). The following example uses DB2 + adapter: + + + getMessage(); + } +?>]]> + + + The next step is opening a new Doctrine_Connection. + + + ]]> + + + Lazy Connections + + Lazy-connecting to database is handled via Doctrine_Db wrapper. When + using Doctrine_Db instead of PDO / Doctrine_Adapter, lazy-connecting to + database is being performed (that means Doctrine will only connect to + database when needed). + + + + This feature can be very useful when using for example page caching, + hence not actually needing a database connection on every request. + Remember connecting to database is an expensive operation. + + query('FROM User u'); +?>]]> + + + Managing Connections + + From the start Doctrine has been designed to work with multiple + connections. Unless separately specified Doctrine always uses the current + connection for executing the queries. The following example uses + openConnection() second argument as an optional connection alias. + + + openConnection(new PDO('dsn','username','password'), 'connection 1'); +?>]]> + + + For convenience Doctrine_Manager provides static method connection() + which opens new connection when arguments are given to it and returns the + current connection when no arguments have been speficied. + + + ]]> + + + The current connection is the lastly opened connection. + + + openConnection(new PDO('dsn2','username2','password2'), 'connection 2'); + + $manager->getCurrentConnection(); // $conn2 +?>]]> + + + You can change the current connection by calling setCurrentConnection(). + + + + setCurrentConnection('connection 1'); + + $manager->getCurrentConnection(); // $conn + +?>]]> + + + + You can iterate over the opened connection by simple passing the manager + object to foreach clause. This is possible since Doctrine_Manager + implements special IteratorAggregate interface. + + + ]]> + + + Connection-component binding + + + Doctrine allows you to bind connections to components (= your + ActiveRecord? classes). This means everytime a component issues a query + or data is being fetched from the table the component is pointing at + Doctrine will use the bound connection. + + + openConnection(new PDO('dsn','username','password'), 'connection 1'); + + $conn2 = $manager->openConnection(new PDO('dsn2','username2','password2'), 'connection 2'); + + $manager->bindComponent('User', 'connection 1'); + + $manager->bindComponent('Group', 'connection 2'); + + $q = new Doctrine_Query(); + + // Doctrine uses 'connection 1' for fetching here + $users = $q->from('User u')->where('u.id IN (1,2,3)')->execute(); + + // Doctrine uses 'connection 2' for fetching here + $groups = $q->from('Group g')->where('g.id IN (1,2,3)')->execute(); +?>]]> +