Multiple Connections

Titi can work with multiple conections. Most of the static functions work with an optional connection name as an extra parameter. For the ORM::configure method, this means that when passing connection strings for a new connection, the second parameter, which is typically omitted, should be null. In all cases, if a connection name is not provided, it defaults to ORM::DEFAULT_CONNECTION.

When chaining, once for_table() has been used in the chain, remaining calls in the chain use the correct connection.

The connection to use can be specified in two separate ways. To indicate a default connection key for a subclass of Model, create a public static property in your model class called $_connection_name.

<?php
// Default connection
ORM::configure('sqlite:./example.db');

// A named connection, where 'remote' is an arbitrary key name
ORM::configure('mysql:host=localhost;dbname=my_database', null, 'remote');
ORM::configure('username', 'database_user', 'remote');
ORM::configure('password', 'top_secret', 'remote');

// Using default connection
$person = ORM::for_table('person')->find_one(5);

// Using default connection, explicitly
$person = ORM::for_table('person', ORM::DEFAULT_CONNECTION)->find_one(5);

// Using named connection
$person = ORM::for_table('different_person', 'remote')->find_one(5);

// A named connection, where 'alternate' is an arbitray key name
ORM::configure('sqlite:./example2.db', null, 'alternate');

class SomeClass extends Model
{
    public static $_connection_name = 'alternate';
}

The connection to use can also be specified as an optional additional parameter to OrmWrapper::for_table(), or to Model::factory(). This will override the default setting (if any) found in the $_connection_name static property.

<?php
$person = Model::factory('Author', 'alternate')->find_one(1);  // Uses connection named 'alternate'

The connection can be changed after a model is populated, should that be necessary:

<?php

$person = Model::factory('Author')->find_one(1);     // Uses default connection
$person->orm = Model::factory('Author', 'alternate');  // Switches to connection named 'alternate'
$person->name = 'Foo';
$person->save();                                     // *Should* now save through the updated connection

Notes

  • There is no support for joins across connections
  • As the Model methods has_one, has_many and belongs_to don’t require joins, these should work as expected, even when the objects on opposite sides of the relation belong to diffrent connections. The has_many_through relationship requires joins, and so will not reliably work across different connections.
  • Multiple connections do not share configuration settings. This means if one connection has logging set to true and the other does not, only queries from the logged connection will be available via ORM::get_last_query() and ORM::get_query_log().
  • ORM::get_connection_names(), which returns an array of connection names.
  • Caching should work with multiple connections (remember to turn caching on for each connection), but the unit tests are not robust. Please report any errors.

Supported Methods

In each of these cases, the $connection_name parameter is optional, and is an arbitrary key identifying the named connection.

  • ORM::configure($key, $value, $connection_name)
  • ORM::for_table($table_name, $connection_name)
  • ORM::set_db($pdo, $connection_name)
  • ORM::get_db($connection_name)
  • ORM::raw_execute($query, $parameters, $connection_name)
  • ORM::get_last_query($connection_name)
  • ORM::get_query_log($connection_name)

Of these methods, only ORM::get_last_query($connection_name) does not fallback to the default connection when no connection name is passed. Instead, passing no connection name (or null) returns the most recent query on any connection.