PHP Classes

File: site/lib/DB/couch/doc/couch_replicator.md

Recommend this page to a friend!
  Classes of Muhammad Mengrani   PHP CouchDB Product CRUD   site/lib/DB/couch/doc/couch_replicator.md   Download  
File: site/lib/DB/couch/doc/couch_replicator.md
Role: Auxiliary data
Content type: text/plain
Description: Auxiliary data
Class: PHP CouchDB Product CRUD
Manage products stored in a CouchDB database
Author: By
Last change: Update of site/lib/DB/couch/doc/couch_replicator.md
Date: 5 months ago
Size: 7,613 bytes
 

Contents

Class file image Download
This section give details on using the couchReplicator object. Replication of CouchDB databases ================================ CouchDB supports replicating a database on other CouchDB databases. Think of replication as a copy-paste operation on databases. The couchReplicator object is a simple abstraction of the CouchDB replication model. Those replication features are available in CouchDB 0.11 . At the time of this coding, canceling a continuous replication doesn't seem to always work. To create a new couchReplicator object, you first have to include necessary files, and then instanciate the object, passing in argument a couchClient instance. <?PHP require_once "lib/couch.php"; require_once "lib/couchClient.php"; require_once "lib/couchDocument.php"; require_once "lib/couchReplicator.php"; $client = new couchClient ("http://localhost:5984/","mydb" ); // I create a replicator instance $replicator = new couchReplicator($client); Replication Basics ================== To replicate a database to another existing database, use the **to()** method. Example : $client = new couchClient ("http://localhost:5984/","mydb" ); // I create a replicator instance $replicator = new couchReplicator($client); $response = $replicator->to("http://another.server.com:5984/mydb"); // database http://localhost:5984/mydb will be replicated to http://another.server.com:5984/mydb Note that you can replicate on a local databse to, eg : $response = $replicator->to("mydb_backup"); // database http://localhost:5984/mydb will be replicated to http://localhost:5984/mydb_backup To replicate from a database to an existing database, use the **from()** method. $response = $replicator->from("http://another.server.com:5984/mydb"); // database http://another.server.com:5984/mydb will be replicated to http://localhost:5984/mydb Please note that CouchDB developpers hardly suggest to use the Pull replication mode : that means to prefer the "from()" method. Auto-creating the target database --------------------------------- The **create_target()** chainable method enables CouchDB to automatically create the target database, in case it doesn't exist. Example : $response = $replicator->create_target()->from("http://another.server.com:5984/mydb"); Which is equivalent to : $replicator->create_target(); $response = $replicator->from("http://another.server.com:5984/mydb"); If the target database already exist, the create_target() method has no use. Replicating only selected documents ----------------------------------- To replicate only some documents, pass their ids to the **doc_ids()** chainable method. Example : $replicator->doc_ids( array ("some_doc", "some_other_doc") )->from("http://another.server.com:5984/mydb"); This code will replicate documents "some_doc" and "some_other_doc" of database "http://another.server.com:5984/mydb" to database "http://localhost:5984/mydb" Continuous replication ====================== A continuous replication is a replication that is permanent : once set, any change to the source database will be automatically propagated to the destination database. Setting up continuous replication --------------------------------- To setup a continuous replication, use the **continuous()** chainable method. Example : // setup a continuous replication $replicator->continuous()->from("http://another.server.com:5984/mydb"); // create a couchClient instance on the source database $client2 = new couchClient("http://another.server.com:5984/","mydb"); // create and record a document on the source database $doc = new stdClass(); $doc->_id = "some_doc_on_another_server"; $doc->type = "foo"; $client2->storeDoc( $doc ); // let some time for CouchDB to replicate sleep(10); // read the document from the destination database $doc = $client->getDoc("some_doc_on_another_server"); echo $doc->type; Cancelling a continuous replication ----------------------------------- To cancel a previously setup continuous replication, use the **cancel()** chainable method. Example : // setup a continuous replication $replicator->continuous()->from("http://another.server.com:5984/mydb"); (...) //code code code // remove the continuous replication $replicator->cancel()->from("http://another.server.com:5984/mydb"); Filtered replication ==================== To have a full control over which document should be replicated, setup a filter definition on the source database. Then use the **filter()** chainable method to filter replicated documents. // create a couchClient instance pointing to the source database $source_client = new couchClient("http://localhost:5984","mydb"); // create a couchClient instance pointing to the target database $target_client = new couchClient("http://another.server.com:5984","mydb") // create a design doc $doc = new stdClass(); $doc->_id = "_design/replication_rules"; $doc->language = "javascript"; // create a "no_design_doc" filter : only documents without the string "_design" will be replicated $doc->filters = array ( "no_design_doc" => "function (doc, req) { if ( doc._id.match('_design') ) { return false; } else { return true; } }" ); // store the design doc in the SOURCE database $target_client->storeDoc($doc); //create a couchReplicator instance on the destination database $replicator = new couchReplicator($target_client); // replicate source database to target database, using the "no_design_doc" filter $replicator->filter('replication_rules/no_design_doc')->from($source_client->getDatabaseUri()); Using request parameters in replication filters ----------------------------------------------- Filters can have a query parameters. This allows more generic filter codes. Let's modify the filter code above to pass the string to compare the document id to via query parameters : // create a couchClient instance pointing to the source database $source_client = new couchClient("http://localhost:5984","mydb"); // create a couchClient instance pointing to the target database $target_client = new couchClient("http://another.server.com:5984","mydb") // create a design doc $doc = new stdClass(); $doc->_id = "_design/replication_rules"; $doc->language = "javascript"; // create a "no_design_doc" filter : only documents without the string "_design" will be replicated $doc->filters = array ( "no_str_in_doc" => "function (doc, req) { if ( doc._id.match( req.query.needle ) ) { return false; } else { return true; } }" ); // store the design doc in the SOURCE database $target_client->storeDoc($doc); //create a couchReplicator instance on the destination database $replicator = new couchReplicator($target_client); // replicate source database to target database, using the "no_str_in_doc" filter, and setting needle to "_design" $params = array ("needle"=>"_design"); $replicator->query_params($params)->filter('replication_rules/no_str_in_doc')->from($source_client->getDatabaseUri()); Replication of individual couchDocuments ======================================== Please read the couchDocument documentation to learn how to simply replicate a document to or from a database to another