Return-Path: Delivered-To: apmail-db-derby-commits-archive@www.apache.org Received: (qmail 59640 invoked from network); 27 Mar 2008 17:42:02 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 27 Mar 2008 17:42:02 -0000 Received: (qmail 48942 invoked by uid 500); 27 Mar 2008 17:42:01 -0000 Delivered-To: apmail-db-derby-commits-archive@db.apache.org Received: (qmail 48911 invoked by uid 500); 27 Mar 2008 17:42:01 -0000 Mailing-List: contact derby-commits-help@db.apache.org; run by ezmlm Precedence: bulk list-help: list-unsubscribe: List-Post: Reply-To: "Derby Development" List-Id: Delivered-To: mailing list derby-commits@db.apache.org Received: (qmail 48900 invoked by uid 99); 27 Mar 2008 17:42:01 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 27 Mar 2008 10:42:01 -0700 X-ASF-Spam-Status: No, hits=-2000.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 27 Mar 2008 17:41:15 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id DD0341A9832; Thu, 27 Mar 2008 10:41:32 -0700 (PDT) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r641923 - in /db/derby/docs/trunk/src: adminguide/ ref/ tuning/ Date: Thu, 27 Mar 2008 17:41:20 -0000 To: derby-commits@db.apache.org From: chaase3@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20080327174132.DD0341A9832@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: chaase3 Date: Thu Mar 27 10:41:12 2008 New Revision: 641923 URL: http://svn.apache.org/viewvc?rev=641923&view=rev Log: DERBY-3169: Add documentation for replication New files for Admin Guide, Reference Manual, Tuning Derby; modified Derby properties table in Tuning Guide. Added: db/derby/docs/trunk/src/adminguide/cadminreplication.dita (with props) db/derby/docs/trunk/src/adminguide/cadminreplicfailover.dita (with props) db/derby/docs/trunk/src/adminguide/cadminreplicfailures.dita (with props) db/derby/docs/trunk/src/adminguide/cadminreplicsecurity.dita (with props) db/derby/docs/trunk/src/adminguide/cadminreplicstartrun.dita (with props) db/derby/docs/trunk/src/adminguide/cadminreplicstop.dita (with props) db/derby/docs/trunk/src/ref/rrefattribfailover.dita (with props) db/derby/docs/trunk/src/ref/rrefattribslavehost.dita (with props) db/derby/docs/trunk/src/ref/rrefattribslaveport.dita (with props) db/derby/docs/trunk/src/ref/rrefattribstartmaster.dita (with props) db/derby/docs/trunk/src/ref/rrefattribstartslave.dita (with props) db/derby/docs/trunk/src/ref/rrefattribstopmaster.dita (with props) db/derby/docs/trunk/src/ref/rrefattribstopslave.dita (with props) db/derby/docs/trunk/src/tuning/rtunproperlogbuffersize.dita (with props) db/derby/docs/trunk/src/tuning/rtunpropermaxlogshippinginterval.dita (with props) db/derby/docs/trunk/src/tuning/rtunproperminlogshippinginterval.dita (with props) db/derby/docs/trunk/src/tuning/rtunproperverbose.dita (with props) Modified: db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap db/derby/docs/trunk/src/ref/refderby.ditamap db/derby/docs/trunk/src/tuning/ctunproper22250.dita db/derby/docs/trunk/src/tuning/tuningderby.ditamap Added: db/derby/docs/trunk/src/adminguide/cadminreplication.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminreplication.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/adminguide/cadminreplication.dita (added) +++ db/derby/docs/trunk/src/adminguide/cadminreplication.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,99 @@ + + + + + +Replicating databases +Replication is an important feature of a robust database management +system. In , you +start database replication by using connection URL attributes. + + +replicating databases +database replication + +

The replication capability of + has the following +features:

+
    +
  • One master, one slave: A replicated database resides in two locations +and is managed by two different + instances. One of these + instances has the +master role for this database, and the other has the slave role. +Typically, the master and slave run on different nodes, but this is not a +requirement. Together, the master and its associated slave represent a +replication pair. +
    • +
  • Roll-forward shipped log: Replication is based on shipping the + transaction log from +the master to the slave, and then rolling forward the operations described in +the log to the slave database. +
    • +
  • Asymmetry: Only the master processes transactions. The slave +processes no transactions, not even read operations. +
    • +
  • Asynchronicity: Transactions are committed on the master without +waiting for the slave. The shipping of the transaction log to the slave is +performed regularly, and is completely decoupled from the transaction execution +at the master. This may lead to a few lost transactions if the master crashes. +
    • +
  • Shared nothing: Apart from the network line, no hardware is assumed to be +shared. +
    • +
  • Replication granularity: The granularity for replication is exactly +one database. However, one + instance may have +different roles for different databases. For example, one + instance may have the +following roles, all at the same time: +
      +
    • The master role for one database D1 replicated to one node
      • +
    • The slave role for a database D2 replicated from another node
      • +
    • The normal, non-replicated, role for a database D3
      • +
    +
    • +
+

Replication builds on +'s ability to recover +from a crash by starting with a backup and rolling forward +'s transaction log +files. The master sends log records to the slave using a network connection. The +slave then writes these log records to its local log and redoes them. +

+

If the master fails, the slave completes the recovery by redoing the log that +has not already been processed. The state of the slave after this recovery is +close to the state the master had when it crashed. However, some of the last +transactions performed on the master may not have been sent to the slave and may +therefore not be reflected. When the slave has completed the recovery work, it +is transformed into a normal + instance that is ready +to process transactions. For more details, see + and +. +

+

Several Derby properties allow you to specify the size of the replication +log buffers and the intervals between log shipments, as well as whether +replication messages are logged. See + for details.

+

You can perform replication on a database that runs in either embedded mode +or Network Server mode. +

+ + Propchange: db/derby/docs/trunk/src/adminguide/cadminreplication.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/adminguide/cadminreplicfailover.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminreplicfailover.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/adminguide/cadminreplicfailover.dita (added) +++ db/derby/docs/trunk/src/adminguide/cadminreplicfailover.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,54 @@ + + + + + +Forcing a failover + +replicating databasesforcing failover +database replicationforcing failover + + +

At any time, you can transform the + database that has the +slave role into a normal + database that can +process transactions. This transformation from being a slave to becoming an +active database is +called failover. During failover, the slave applies the parts of the +transaction log that have not yet been processed. It then undoes operations that +belong to uncommitted transactions, resulting in a transaction-consistent state +that includes all transactions whose commit log record has been sent to the +slave.

+

You perform failover from the master system. To do so, you connect to the +database on the master system using +the failover=true connection URL attribute. For example, for a database +named wombat, you might specify the following connection URL: +

+ +jdbc:derby:wombat;failover=true + +

If the network connection between the master system and the slave system is +lost, you can perform failover from the slave system.

+

See the for details about the +failover=true attribute.

+

There is no automatic failover or restart of replication after one of the +instances has failed.

+ + Propchange: db/derby/docs/trunk/src/adminguide/cadminreplicfailover.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/adminguide/cadminreplicfailures.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminreplicfailures.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/adminguide/cadminreplicfailures.dita (added) +++ db/derby/docs/trunk/src/adminguide/cadminreplicfailures.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,121 @@ + + + + + +Replication failure handling + +replicating databasesfailure handling +database replicationfailure handling + + +

Replication can encounter several failure situations. The following table +lists these situations and describes the actions that + takes as a result. +

+ +Replication failure handling + + + +Failure situation +Action taken + + + + +Master loses connection with slave. +Transactions are allowed to continue processing while the +master tries to reconnect with the slave. Log records generated while the +connection is down are buffered in main memory. If the log buffer reaches its +size limit before the connection can be reestablished, the master replication +functionality is stopped. You can use the property +derby.replication.logBufferSize to configure the size limit of the +buffer; see for +details. + + +Slave loses connection with master. +The slave tries to reestablish the connection with the +master by listening on the specified host and port. It will not give up until it +is explicitly requested to do so by either the failover=true or +stopSlave=true connection URL attribute. If a failover is requested, the +slave applies all received log records and boots the database as described in +. If the +stopSlave=true attribute is specified, the slave database is shut down +without further actions. + + +Two different masters of database D try to replicate to +the same slave. +The slave will only accept the connection from the first +master attempting to connect. Note that authentication is required to start +both the slave and the master, as described in +. + + +The master and slave + instances are not at +the same version. + +An exception is raised and replication does not start. + + + +The master + instance crashes, then +restarts. +Replication must be restarted, as described in +. + + +The master + instance is not able to +send log data to the slave at the same pace as the log is generated. The main +memory log buffer gradually fills up and eventually becomes full. +The master notices that the main memory log buffer is +filling up. It first tries to increase the speed of the log shipment to keep +the amount of log in the buffer below the maximum. If that is not enough to +keep the buffer from getting full, the response time of transactions may +increase for as long as log shipment has trouble keeping up with the amount of +generated log records. You can use properties to tune both the log buffer size +and the minimum and maximum interval between consecutive log shipments. See + for details. + + +The slave + instance crashes. +The master sees this as a lost connection to the slave. +The master tries to reestablish the connection until the replication log buffer +is full. Replication is then stopped on the master. Replication must be +restarted, as described in +. + + +An unexpected failure is encountered. +Replication is stopped. The other + instance of the +replication pair is notified of the decision if the network connection is still +alive. + + + +
+ + Propchange: db/derby/docs/trunk/src/adminguide/cadminreplicfailures.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/adminguide/cadminreplicsecurity.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminreplicsecurity.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/adminguide/cadminreplicsecurity.dita (added) +++ db/derby/docs/trunk/src/adminguide/cadminreplicsecurity.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,85 @@ + + + + + +Replication and security + +replicating databasessecurity +database replicationsecurity + + +

If you want to perform replication with the security manager enabled, you +must modify the security policy file on both the master and slave systems to +allow the master-slave network connection. The section to be modified is the +one following this line:

+ +grant codeBase "${derby.install.url}derby.jar" + +

Add the following permission to the policy file on the master system:

+ + permission java.net.SocketPermission "slaveHost:slavePort", "connect,resolve"; + +

Add the following permission to the policy file on the slave system:

+ + permission java.net.SocketPermission "slaveHost", "accept,resolve"; + +

slaveHost and slavePort are the values you specify for the +slaveHost=hostname and slavePort=portValue attributes, which are +described in the .

+

See for +details on the security policy file.

+

Depending on the security mode is running under, the +measures described in the following table are enforced when you specify the +replication-related connection URL attributes. +

+ +Replication behavior with <ph +conref="../conrefs.dita#prod/productshortname"></ph> security + + + +Security mode +Replication attribute requirements + + + + +No security +Anyone may specify the replication attributes + + +Authentication is turned on +Normal connection policy: specify +valid user=userName and password=userPassword attributes + + +Authorization is turned on +The user=userName and password=userPassword +attributes must be valid, and the user must be the owner of the replicated +database + + + +
+ + Propchange: db/derby/docs/trunk/src/adminguide/cadminreplicsecurity.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/adminguide/cadminreplicstartrun.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminreplicstartrun.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/adminguide/cadminreplicstartrun.dita (added) +++ db/derby/docs/trunk/src/adminguide/cadminreplicstartrun.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,92 @@ + + + + + +Starting and running replication + +replicating databasesstarting and running +database replicationstarting and running + + +

Each replicated database is replicated from a master to a slave version of +that database. Initially there is no replication; a master database must be +created before it can be replicated. The database may, of course, be empty when +replication starts. On the other hand, replication does not need to be specified +immediately after the database is created; it can be initiated at any time after +the database is created. +

+

Before you start replication, you must boot the master database and then +copy the database to the slave location. To ensure that the master database +is not modified between the time you start the file-system copy and the time +you start replication, you must freeze the master database. Follow these +steps to start replication: +

+
    +
  1. Boot the database on the master system.
    2. +
  2. When you are ready to start replication, freeze the master database by +calling the SYSCS_UTIL.SYSCS_FREEZE_DATABASE procedure, as +shown in the following example: +CallableStatement cs = conn.prepareCall +("CALL SYSCS_UTIL.SYSCS_FREEZE_DATABASE()"); +cs.execute(); +cs.close(); +This procedure ensures that all data pages and the log are written to disk, +and blocks modifications to the database until replication has successfully +started.
    3. +
  3. Copy the database to the slave location.
    4. +
  4. Start slave replication mode on the Derby instance that is acting +as the slave for the database. To start slave replication, use the +startSlave=true attribute and, optionally, the slaveHost=hostname +and slavePort=portValue attributes. For example, for a database named +wombat, you might use the following connection URL: + +jdbc:derby:wombat;startSlave=true +
    5. +
  5. Start master replication mode on the Derby instance that is acting as the +master for the database. To start replication, connect to the database on the +master system using the startMaster=true attribute in conjunction with +the slaveHost=hostname attribute (and, optionally, the +slavePort=portValue attribute). For example, you might use the following +connection URL: + +jdbc:derby:wombat;startMaster=true;slaveHost=myremotesystem + +A successful use of the startMaster=true attribute will also unfreeze the +database.
    6. +
+

See the for details about these +attributes.

+

After replication has been started, the slave +is ready to receive logged operations from the master. The master can now +continue to process transactions. From this point on, the master forwards all +logged operations to the slave in chunks. The slave repeats +these operations by applying the contents of the transaction log, but does +not process any other operations. Attempts to connect to the slave database are +refused. In case of failure, the slave can recover to the state the master was +in at the time the last chunk of the transaction log was sent. +

+

While replication is running, neither the slave or the master database is +permitted to be shut down. Replication must be stopped before you can shut down +either the slave or the master database. There is one exception to this rule: +if the entire system is shut down, the peer that is shut down notifies the other +replication peer that replication is stopped.

+ + Propchange: db/derby/docs/trunk/src/adminguide/cadminreplicstartrun.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/adminguide/cadminreplicstop.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/cadminreplicstop.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/adminguide/cadminreplicstop.dita (added) +++ db/derby/docs/trunk/src/adminguide/cadminreplicstop.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,47 @@ + + + + + +Stopping replication + +replicating databasesstopping +database replicationstopping + + +

To stop replication of a database, connect to the master database using the +stopMaster=true connection URL attribute. The master sends the remaining +log records that await shipment, and then sends a stop replication command to +the slave. The slave then writes all logs to disk and shuts down the database. +For example, for a database named wombat, you might specify the +following connection URL:

+ +jdbc:derby:wombat;stopMaster=true + +

To stop replication on the slave system if the connection to the master is +lost, use the stopSlave=true connection URL attribute. +

+

See the for details about these +attributes.

+

You cannot resume replication after it has been stopped. You need to start +replication over again from the beginning using the startMaster=true +attribute, as described in +. +

 + Propchange: db/derby/docs/trunk/src/adminguide/cadminreplicstop.dita ------------------------------------------------------------------------------ svn:eol-style = native Modified: db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap?rev=641923&r1=641922&r2=641923&view=diff ============================================================================== --- db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap (original) +++ db/derby/docs/trunk/src/adminguide/derbyadmin.ditamap Thu Mar 27 10:41:12 2008 @@ -261,6 +261,18 @@ + + + + + + + + + + + + Modified: db/derby/docs/trunk/src/ref/refderby.ditamap URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=641923&r1=641922&r2=641923&view=diff ============================================================================== --- db/derby/docs/trunk/src/ref/refderby.ditamap (original) +++ db/derby/docs/trunk/src/ref/refderby.ditamap Thu Mar 27 10:41:12 2008 @@ -600,6 +600,8 @@ + + @@ -615,6 +617,18 @@ + + + + + + + + + + + + Added: db/derby/docs/trunk/src/ref/rrefattribfailover.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribfailover.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/ref/rrefattribfailover.dita (added) +++ db/derby/docs/trunk/src/ref/rrefattribfailover.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,83 @@ + + + + + +failover=true attribute + +failover=true database connection URL +attributereplicating databasesforcing +failoverdatabase +replicationforcing failover +databasesattributes, forcing +failover +attributesfailover + + + +
Function +

Stops database replication on the slave system and converts the slave +database into a normal database.

+

If you specify the failover=true attribute on the master, the +attribute sends the remaining log records to the slave instance and then sends a +failover message to the slave. The replication functionality and the database +are then shut down on the master system. If failover is successful, an exception +with the error code XRE20 is thrown. Hence, when issued on the master, the +failover=true attribute does not return a valid connection.

+

You may specify this attribute on the slave only if the network connection +between the master and the slave is down.

+

When you specify this attribute on the slave, or when a failover message is +sent as part of the execution of the failover=true attribute on the +master, all transaction log chunks that have been received from the master are +written to disk. The slave replication functionality is shut down, and the boot +process of the database is allowed to complete. The database is now in a +transaction consistent state, reflecting all transactions whose commit log +records were received from the master. When issued on the slave, the +failover=true command returns a valid connection.

+

The instance where +this command is issued must be serving the named database in replication mode. +

+

For more information, see the topics under "Replicating databases" in the +.

+
+
Combining with other attributes +

You must specify a database name in the connection URL, either in the +subprotocol or by using the databaseName=nameofDatabase +attribute.

+

If authentication is turned on, you must also specify +this attribute in conjunction with the user=userName and +password=userPassword +attributes. Authorization for the master database cannot be checked when the +network connection is down, so the requirement that the user must be the +database owner is not enforced.

+

You may not specify this attribute in conjunction with any attributes not +mentioned in this section.

+
+Examples +-- start failover from master using database name in subprotocol, +-- authorization +jdbc:derby:myDB;failover=true;user=mary;password=little88lamb +-- start failover using databaseName attribute, no security +jdbc:derby:;databaseName=myDB;failover=true; + + + Propchange: db/derby/docs/trunk/src/ref/rrefattribfailover.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/ref/rrefattribslavehost.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribslavehost.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/ref/rrefattribslavehost.dita (added) +++ db/derby/docs/trunk/src/ref/rrefattribslavehost.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,58 @@ + + + + + +slaveHost=hostname attribute + +slaveHost=hostname database connection URL +attributereplicating databasesspecifying the +slave hostdatabase +replicationspecifying the slave +hostdatabasesattributes, +specifying replication slave host +attributesslaveHost + + + +
Function +

Specifies the system that will serve as the slave for database replication. +

+

For more information, see the topics under "Replicating databases" in the +.

+
+
Combining with other attributes +

This attribute must be specified in conjunction with the startMaster=true +attribute. It may be specified in conjunction with the startSlave=true +attribute; if it is not, the default value is localhost.

+

This attribute may be specified only in conjunction with the other attributes +permitted with the startMaster=true and startSlave=true +attributes.

+
+Examples +

For examples, see startMaster=true +and startSlave=true. +

+ + + Propchange: db/derby/docs/trunk/src/ref/rrefattribslavehost.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/ref/rrefattribslaveport.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribslaveport.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/ref/rrefattribslaveport.dita (added) +++ db/derby/docs/trunk/src/ref/rrefattribslaveport.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,59 @@ + + + + + +slavePort=portValue attribute + +slavePort=portValue database connection URL +attributereplicating databasesspecifying the +slave portdatabase +replicationspecifying the slave +portdatabasesattributes, +specifying replication slave port +attributesslavePort + + + +
Function +

Specifies the port that the slave system will use in database replication. +

+

For more information, see the topics under "Replicating databases" in the +.

+
+
Combining with other attributes +

This attribute may be specified in conjunction with the startMaster=true +attribute and the startSlave=true +attribute. If it is not specified, the default port value is +4851.

+

This attribute may be specified only in conjunction with the other attributes +permitted with the startMaster=true and startSlave=true +attributes.

+
+Examples +

For examples, see startMaster=true +and startSlave=true. +

+ + + Propchange: db/derby/docs/trunk/src/ref/rrefattribslaveport.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/ref/rrefattribstartmaster.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribstartmaster.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/ref/rrefattribstartmaster.dita (added) +++ db/derby/docs/trunk/src/ref/rrefattribstartmaster.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,71 @@ + + + + + +startMaster=true attribute + +startMaster=true database connection URL +attributereplicating databasesstarting the +masterdatabase replicationstarting +the masterdatabasesattributes, +starting the replication master +attributesstartMaster + + + +
Function +

Starts replication of a database in master mode. The specified database must +have been created before you specify this attribute.

+

For more information, see the topics under "Replicating databases" in the +.

+
+
Combining with other attributes +

You must specify a database name in the connection URL, either in the +subprotocol or by using the databaseName=nameofDatabase +attribute.

+

You must specify this attribute in conjunction with the slaveHost=hostname +attribute. You may also specify this attribute in conjunction with the slavePort=portValue +attribute. If you do not specify the slavePort=portValue attribute, the +default port value is 4851.

+

If authentication or authorization is turned on, you +must also specify this attribute in conjunction with the user=userName and +password=userPassword +attributes. If authorization is turned on, the user must be the database owner. +

+

You may not specify this attribute in conjunction with any attributes not +mentioned in this section.

+
+Examples +-- start master using database name in subprotocol, default slave +-- port, authorization +jdbc:derby:myDB;startMaster=true;slaveHost=elsewhere;user=mary; + password=little88lamb +-- start master using databaseName attribute, non-default slave +-- port, no security +jdbc:derby:;databaseName=myDB;startMaster=true;slaveHost=elsewhere; + slavePort=4852 + + + Propchange: db/derby/docs/trunk/src/ref/rrefattribstartmaster.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/ref/rrefattribstartslave.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribstartslave.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/ref/rrefattribstartslave.dita (added) +++ db/derby/docs/trunk/src/ref/rrefattribstartslave.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,88 @@ + + + + + +startSlave=true attribute + +startSlave=true database connection URL +attributereplicating databasesstarting the +slavedatabase replicationstarting +the slavedatabasesattributes, +starting the replication slave +attributesstartSlave + + + +
Function +

Starts replication of a database in slave mode. Before you specify this +attribute, you must boot the database on the master system, freeze it, and then +perform a file system copy of the database to the slave system. +

+

The startSlave=true attribute does the following:

+
    +
  1. Partially boots the specified database
    2. +
  2. Starts to listen on the specified port and accepts a connection from the +master
    3. +
  3. Hangs until the master has connected to it
    4. +
  4. Reports the startup status to the caller (whether it has started, and if +not, why not)
    5. +
  5. Continually receives chunks of the transaction log from the master and +applies the operations in the transaction log to the slave database
    6. +
+

If replication is started successfully, an exception with the error code +XRE08 is thrown. Hence, the startSlave=true attribute does not return a +valid connection.

+

For more information, see the topics under "Replicating databases" in the +.

+
+
Combining with other attributes +

You must specify a database name in the connection URL, either in the +subprotocol or by using the databaseName=nameofDatabase +attribute.

+

You may specify this attribute in conjunction with the slaveHost=hostname +attribute. If you do not specify the slaveHost=hostname attribute, the +default value is localhost.

+

You may also specify this attribute in conjunction with the slavePort=portValue +attribute. If you do not specify the slavePort=portValue attribute, the +default port value is 4851.

+

If authentication or authorization is turned on, you +must also specify this attribute in conjunction with the user=userName and +password=userPassword +attributes. If authorization is turned on, the user must be the database owner. +

+

You may not specify this attribute in conjunction with any attributes not +mentioned in this section.

+
+Examples +-- start slave using database name in subprotocol, default slave host +-- and port, authorization +jdbc:derby:myDB;startslave=true;user=mary;password=little88lamb +-- start slave using databaseName attribute, non-default slave host +-- and port, no security +jdbc:derby:;databaseName=myDB;startSlave=true;slaveHost=localhost; + slavePort=4852 + + + Propchange: db/derby/docs/trunk/src/ref/rrefattribstartslave.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/ref/rrefattribstopmaster.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribstopmaster.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/ref/rrefattribstopmaster.dita (added) +++ db/derby/docs/trunk/src/ref/rrefattribstopmaster.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,66 @@ + + + + + +stopMaster=true attribute + +stopMaster=true database connection URL +attributereplicating databasesstopping the +masterdatabase replicationstopping +the masterdatabasesattributes, +stopping the replication master +attributesstopMaster + + + +
Function +

Stops database replication on the master system. This attribute sends a +stop-slave message to the slave system if the network connection is working. +Then it shuts down all replication-related functionality, without shutting down +the specified database.

+

The instance where +this attribute is specified must be the replication master for the specified +database.

+

For more information, see the topics under "Replicating databases" in the +.

+
+
Combining with other attributes +

You must specify a database name in the connection URL, either in the +subprotocol or by using the databaseName=nameofDatabase +attribute.

+

If authentication or authorization is turned on, you +must also specify this attribute in conjunction with the user=userName and +password=userPassword +attributes. If authorization is turned on, the user must be the database owner. +

+

You may not specify this attribute in conjunction with any attributes not +mentioned in this section.

+
+Examples +-- stop master using database name in subprotocol, authorization +jdbc:derby:myDB;stopMaster=true;user=mary;password=little88lamb +-- stop master using databaseName attribute, no security +jdbc:derby:;databaseName=myDB;stopMaster=true; + + + Propchange: db/derby/docs/trunk/src/ref/rrefattribstopmaster.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/ref/rrefattribstopslave.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefattribstopslave.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/ref/rrefattribstopslave.dita (added) +++ db/derby/docs/trunk/src/ref/rrefattribstopslave.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,76 @@ + + + + + +stopSlave=true attribute + +stopSlave=true database connection URL +attributereplicating databasesstopping the +slavedatabase replicationstopping +the slavedatabasesattributes, +stopping the replication slave +attributesstopSlave + + + +
Function +

Stops database replication on the slave system.

+

You can specify this connection URL attribute only if the network connection +between the master and slave systems is down. If the network connection is +working, the slave system accepts commands only from the master, so you must +specify the stopMaster=true +attribute on the master system to stop replication on both the master and slave +systems.

+

When this attribute is specified, or when a stop-slave message is sent as +part of the execution of the stopMaster=true attribute, all transaction +log chunks that have been received from the master are written to disk. Both the +slave replication functionality and the database are then shut down.

+

The instance where +this attribute is specified must be serving the specified database in +replication slave mode.

+

For more information, see the topics under "Replicating databases" in the +.

+
+
Combining with other attributes +

You must specify a database name in the connection URL, either in the +subprotocol or by using the databaseName=nameofDatabase +attribute.

+

If authentication is turned on, you must also specify +this attribute in conjunction with the user=userName and +password=userPassword +attributes. Authorization for the master database cannot be checked when the +network connection is down, so the requirement that the user must be the +database owner is not enforced.

+

You may not specify this attribute in conjunction with any attributes not +mentioned in this section.

+
+Examples +-- stop slave from master using database name in subprotocol, +-- authorization +jdbc:derby:myDB;stopSlave=true;user=mary;password=little88lamb +-- stop slave using databaseName attribute, no security +jdbc:derby:;databaseName=myDB;stopSlave=true; + + + Propchange: db/derby/docs/trunk/src/ref/rrefattribstopslave.dita ------------------------------------------------------------------------------ svn:eol-style = native Modified: db/derby/docs/trunk/src/tuning/ctunproper22250.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/ctunproper22250.dita?rev=641923&r1=641922&r2=641923&view=diff ============================================================================== --- db/derby/docs/trunk/src/tuning/ctunproper22250.dita (original) +++ db/derby/docs/trunk/src/tuning/ctunproper22250.dita Thu Mar 27 10:41:12 2008 @@ -51,37 +51,37 @@ derby.authentication.ldap.searchAuthDN S, D - +  derby.authentication.ldap.searchAuthPW S, D - +  derby.authentication.ldap.searchBase S, D - +  derby.authentication.ldap.searchFilter S, D - +  derby.authentication.provider S, D - +  derby.authentication.server S, D - +  derby.connection.requireAuthentication S, D - +  derby.database.defaultConnectionMode @@ -91,7 +91,7 @@ derby.database.forceDatabaseLock S - +  derby.database.fullAccessUsers @@ -101,7 +101,7 @@ derby.database.noAutoBoot D - +  derby.database.propertiesOnly @@ -116,7 +116,7 @@ derby.infolog.append S - +  derby.jdbc.xaTransactionTimeout @@ -126,12 +126,12 @@ derby.language.logQueryPlan S - +  derby.language.logStatementText S, D - +  derby.locks.deadlockTimeout @@ -159,9 +159,29 @@ X +derby.replication.logBufferSize +S +  + + +derby.replication.maxLogShippingInterval +S +  + + +derby.replication.minLogShippingInterval +S +  + + +derby.replication.verbose +S +  + + derby.storage.initialPages C - +  derby.storage.minimumRecordSize @@ -171,7 +191,7 @@ derby.storage.pageCacheSize S - +  derby.storage.pageReservedSpace @@ -191,37 +211,37 @@ derby.stream.error.field S - +  derby.stream.error.file S - +  derby.stream.error.method S - +  derby.stream.error.logSeverityLevel S - +  derby.system.bootAll S - +  derby.system.durability S - +  derby.system.home S - +  derby.user.UserName Added: db/derby/docs/trunk/src/tuning/rtunproperlogbuffersize.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/rtunproperlogbuffersize.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/tuning/rtunproperlogbuffersize.dita (added) +++ db/derby/docs/trunk/src/tuning/rtunproperlogbuffersize.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,57 @@ + + + + +derby.replication.logBufferSize + +derby.replication.logBufferSize +replicationspecifying log buffer size + + + +
Function +

Specifies the size of the replication log buffers in bytes. These buffers +store the log on the master side before it is shipped to the slave. There is a +total of 10 such buffers. Large buffers increase memory usage but reduce +the chance that the buffers fill up (in turn increasing response time for +transactions on the master, as described in the failure situation "The master + instance is not able +to send log data to the slave at the same pace as the log is generated" in the +topic "Replication failure handling" in the +).

+

The minimum value is 8192 (8 KB). The maximum value is 1048576 (1 MB).

+

You can also use the properties + +and + +to tune the rate at which the log is shipped from the master to the slave.

+
+
Default +

32768 bytes (32KB).

+
+Example +derby.replication.logBufferSize=65536 + +
Scope +

system-wide

+
+
Dynamic or static +

This property is static; if you change it while + is running, the change +does not take effect until you reboot.

+
 Propchange: db/derby/docs/trunk/src/tuning/rtunproperlogbuffersize.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/tuning/rtunpropermaxlogshippinginterval.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/rtunpropermaxlogshippinginterval.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/tuning/rtunpropermaxlogshippinginterval.dita (added) +++ db/derby/docs/trunk/src/tuning/rtunpropermaxlogshippinginterval.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,54 @@ + + + + +derby.replication.maxLogShippingInterval + +derby.replication.maxLogShippingInterval +replicationspecifying maximum log shipping interval + + + +
Function +

Specifies, in milliseconds, the longest interval between two consecutive +shipments of the transaction log from the master to the slave. This property +provides a "soft" guarantee that the slave will not deviate more than this +number of milliseconds from the master.

+

The value specified for the derby.replication.maxLogShippingInterval +property must be at least ten times the value specified for the + +property. If you set derby.replication.maxLogShippingInterval to a lower +value, changes the + +property value to the value of the +derby.replication.maxLogShippingInterval property divided by 10.

+
+
Default +

5000 milliseconds (5 seconds).

+
+Example +derby.replication.maxLogShippingInterval=10000 + +
Scope +

system-wide

+
+
Dynamic or static +

This property is static; if you change it while + is running, the change +does not take effect until you reboot.

+
 Propchange: db/derby/docs/trunk/src/tuning/rtunpropermaxlogshippinginterval.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/tuning/rtunproperminlogshippinginterval.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/rtunproperminlogshippinginterval.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/tuning/rtunproperminlogshippinginterval.dita (added) +++ db/derby/docs/trunk/src/tuning/rtunproperminlogshippinginterval.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,53 @@ + + + + +derby.replication.minLogShippingInterval + +derby.replication.minLogShippingInterval +replicationspecifying minimum log shipping interval + + + +
Function +

Specifies, in milliseconds, the shortest interval between two consecutive +shipments of the transaction log from the master to the slave.

+

The value specified for the derby.replication.minLogShippingInterval +property must be no more than one-tenth the value specified for the + +property. If you set derby.replication.minLogShippingInterval to a +higher value, changes +the derby.replication.minLogShippingInterval property value to the value +of the + +property divided by 10.

+
+
Default +

100 milliseconds.

+
+Example +derby.replication.minLogShippingInterval=500 + +
Scope +

system-wide

+
+
Dynamic or static +

This property is static; if you change it while + is running, the change +does not take effect until you reboot.

+
 Propchange: db/derby/docs/trunk/src/tuning/rtunproperminlogshippinginterval.dita ------------------------------------------------------------------------------ svn:eol-style = native Added: db/derby/docs/trunk/src/tuning/rtunproperverbose.dita URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/rtunproperverbose.dita?rev=641923&view=auto ============================================================================== --- db/derby/docs/trunk/src/tuning/rtunproperverbose.dita (added) +++ db/derby/docs/trunk/src/tuning/rtunproperverbose.dita Thu Mar 27 10:41:12 2008 @@ -0,0 +1,44 @@ + + + + +derby.replication.verbose + +derby.replication.verbose +replicationspecifying message logging + + + +
Function +

Specifies whether replication messages are written to the + log.

+
+
Default +

True.

+
+Example +derby.replication.verbose=false + +
Scope +

system-wide

+
+
Dynamic or static +

This property is static; if you change it while + is running, the change +does not take effect until you reboot.

+
 Propchange: db/derby/docs/trunk/src/tuning/rtunproperverbose.dita ------------------------------------------------------------------------------ svn:eol-style = native Modified: db/derby/docs/trunk/src/tuning/tuningderby.ditamap URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/tuning/tuningderby.ditamap?rev=641923&r1=641922&r2=641923&view=diff ============================================================================== --- db/derby/docs/trunk/src/tuning/tuningderby.ditamap (original) +++ db/derby/docs/trunk/src/tuning/tuningderby.ditamap Thu Mar 27 10:41:12 2008 @@ -288,6 +288,10 @@ + + + +