Vendor lock

vendor/j4mie/paris/docs/connections.rst

@@ -0,0 +1,40 @@
+Multiple Connections
+====================
+
+Paris now works with multiple database conections (and necessarily relies on an updated version of Idiorm that also supports multiple connections). Database connections are identified by a string name, and default to ``OrmWrapper::DEFAULT_CONNECTION`` (which is really ``ORM::DEFAULT_CONNECTION``).
+
+See `Idiorm’s documentation`_ for information about configuring multiple connections.
+
+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``.
+
+.. code-block:: php
+
+    <?php
+    // 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.
+
+.. code-block:: php
+
+    <?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:
+
+.. code-block:: php
+
+    <?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
+
+Queries across multiple connections are not supported. However, as the Paris 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.
+
+.. _Idiorm’s documentation: http://github.com/j4mie/idiorm/