documented master/slave setup for ORM

chatii · Jan 19, 2013 · e006d95 · e006d95
1 parent a145e70
commit e006d95
Showing 1 changed file with 24 additions and 4 deletions.
diff --git a/packages/orm/creating_models.html b/packages/orm/creating_models.html
@@ -175,14 +175,34 @@ <h3 id="relations">protected static $_has_one, $_belongs_to, $_has_many, $_many_
 				<h3 id="connection">protected static $_connection</h3>
 
 				<p>By default this property does not exist and Model::connection() returns <kbd>null</kbd>, but you can set
-				it to any other database name configured in <kbd>app/config/db.php</kbd>. Note however that relations don't
-				work across connections.</p>
+				it to any other database name configured in <kbd>app/config/db.php</kbd>.</p>
 
-				<pre class="php"><code>class Model_Article extends Orm\Model
+				<h3 id="write_connection">protected static $_write_connection</h3>
+
+				<p>If you have a master/slave setup for your database environment, you can use this property to define the
+				connection to use for the write master. If configured, the <kbd>$_connection</kbd> property will be used
+				to connect to the read slaves.</p>
+				<p>By default this property does not exist and Model::connection(true) returns either the configured <kbd>$_connection</kbd>,
+				or <kbd>null</kbd>, but you can set it to any other database name configured in <kbd>app/config/db.php</kbd>.</p>
+
+				<pre class="php"><code>// configuration for single database usage
+class Model_Article extends Orm\Model
 {
-	protected static $_connection = 'articles_database';
+	// 'articles_db' has to be configured in your db.php configuration file
+	protected static $_connection = 'articles_db';
+}
+
+// configuration for master/slave database usage
+class Model_Article extends Orm\Model
+{
+	// 'articles_master_db' and 'articles_slave_db' have to be configured in your db.php configuration file
+	protected static $_write_connection = 'articles_master_db';
+	protected static $_connection = 'articles_slave_db';
 }</code></pre>
 
+				<p class="note">Note that relations do not work across connections, so when you define your connections in the model,
+				make sure your related models have exactly the same configuration, both for reads and writes!</p>
+
 				<h3 id="to_array_exclude">protected static $_to_array_exclude</h3>
 
 				<p>