<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<sect2 id="bidirtransrepl"><title>Bi-Directional Transactional Replication</title>

 <para>Virtuoso supports bi-directional transactional replication via a mechanism 
 of updateable subscriptions.  The following rules and conditions must be observed:</para>

<simplelist>
  <member>Every table has only one publisher.</member>
  <member>Only direct subscribers are considered.</member>
  <member>Only replication of tables is allowed.</member>
</simplelist>

 <para>It is assumed that all the tables within a publication have primary keys 
 and that the primary key columns are never modified.</para>

 <para>Every transaction has an origin, i.e. the originating server on which 
 the transaction was performed.</para>

 <para>Modifications to a subscriber come from publisher only using the ordinary 
 transactional replication technique: the subscriber initiates an update and 
 pulls (requests) replication logs from publisher.  The publisher sends 
 the replication log from the replication log files and then places the subscriber 
 into "synced" (or "online") mode.  In this mode the replication logs are sent 
 to subscriber immediately after each COMMIT.</para>

 <para>Data flow from a subscriber to the publisher is very similar: the 
 subscriber initiates the update and pushes replication logs to the publisher.  
 After all replication log data has been sent to the publisher it is put into 
 "synced" mode and will receive modifications immediately after each COMMIT 
 on subscriber.</para>

 <sect3 id="bidirtransreplcreate"><title>Creating Publications for Updateable Subscriptions</title>

  <para>In order to create a publication that allows transaction-based
  replication and updateable subscriptions use the
  <function>repl_publish()</function> with a non-zero third argument.
  Replication feeds from subscribers can be replayed by user different from
  'dba' user.</para>

  <programlisting>repl_publish('foo', 'foo.log', 1, 'demo');</programlisting>

  <para>This will create updateable publication 'foo'. Replication feeds
  from subscribers will be replayed as user 'demo'.</para>
 </sect3>

 <sect3 id="bidirtransrepladdtable"><title>Adding Tables to a Publication</title>

  <para>When a table is added to an updateable publication a new 
  'ROWGUID varchar' column is automatically added to the table.
  This column will be used for conflict resolution (described later).
  If the table already has column with such a name, an existing column
  will be used (with checking for appropriate data type and width).
  ROWGUID columns hold globally unique identifiers of a row and are
  modified after each UPDATE of a row.  ROWGUID column values 
  are OSF DCE 1.1 compliant Universally Unique Identifiers (UUID).</para>

  <para>ROWGUID columns are used for conflict resolution for 
  INSERT/UPDATE/DELETE DML operations.  Basically, if a ROWGUID column 
  that came from a subscriber does not differ from the ROWGUID column 
  of the publisher's table then it is assumed that there is no conflict, 
  otherwise conflict resolution must take place.</para>
 </sect3>

 <sect3 id="bidirtransreplconflictres"><title>Conflict Resolution</title>
  
  <para>Since every table may have only one publisher, conflicts resolution 
  will always take place on the publisher.</para>

  <para>Assume some DML operation that occurred on a subscriber is being replayed
  on publisher.  There may be three types of conflicts:</para>

<orderedlist>
  <listitem><formalpara><title>uniqueness conflict (insert conflict)</title>
   <para>occurs when the row with some primary key &lt;PK&gt; already exists 
   in publisher's table.</para></formalpara></listitem>

  <listitem><formalpara><title>update conflict</title>
   <para>occurs when an UPDATE modifies a row which has already been 
   modified on publisher (by the publisher or another subscriber).</para></formalpara></listitem>

  <listitem><formalpara><title>delete conflict</title>
   <para>occurs when an UPDATE modifies a row or a DELETE removes a row
   that does not exist on publisher anymore.</para></formalpara></listitem>
</orderedlist>

  <para>Every table has a number of conflict resolvers that are used for 
  conflict resolution.  These are stored in DB.DBA.SYS_REPL_CR system table. 
  Each conflict resolver has a type ('I', 'U', or 'D') and an order.  Conflict 
  resolvers are applied in ascending order.</para>

<para>The conflict resolver is a Virtuoso/PL procedure that receives a 
conflicting row from a subscriber and some other arguments.  The conflict 
resolver can modify the row, which is passed as an 'inout' argument.
The conflict resolver should return an integer value, which will be used
for conflict resolution.</para>

Conflict resolvers of different types have different signatures:

<simplelist>
 <member>
   <para><emphasis>'I' - Insert conflict resolvers</emphasis></para>
   <para>(&lt;ALLCOLS&gt;, inout _origin varchar)</para></member>

 <member>
   <para><emphasis>'U' - Update conflict resolvers</emphasis></para>
   <para>(&lt;ALLCOLS&gt;, , &lt;ALLOLDCOLS&gt;, inout _origin varchar)</para></member>

 <member>
   <para><emphasis>'D' - Deletion conflict resolvers</emphasis></para>
   <para>(&lt;ALLOLDCOLS&gt;, inout _origin varchar)</para></member>
   </simplelist>

<para>where</para>

<para>&lt;ALLCOLS&gt; are new values of all columns including the ROWGUID 
column, &lt;ALLOLDCOLS&gt; are old values of all columns, and _origin 
is transaction originator.</para>

<para>Conflict resolvers can return the following integer values; 
The conflict resolver types concerned for each are listed in parentheses:</para>

<itemizedlist>
  <listitem><formalpara><title>0 - can't decide (I, U, D)</title>
	<para>next conflict resolver will be fired.</para></formalpara></listitem>

  <listitem><formalpara><title>1 - subscriber wins (I, U, D)</title>
	<para>DML operation will be applied with &lt;ALLCOLS&gt;
	All the subscribers except originator will receive modifications
	(originator already has them).</para></formalpara></listitem>

  <listitem><formalpara><title>2 - subscriber wins, change origin (I, U)</title>
	<para>DML operation will be applied with &lt;ALLCOLS&gt; and origin
	of transaction will be changed to publisher's server name.
	All the subscribers (including originator) will receive modifications.
	This return value is useful when conflict resolver changed some of
	the columns of the row that were passed in.
    Although all parameters of conflict resolver are inout
    only changing of &lt;ALLCOLS&gt; (non-PK columns) parameters 
	makes sense.</para></formalpara></listitem>

  <listitem><formalpara><title>3 - publisher wins (U)</title>
	<para>DML operation will be applied with &lt;ALLCOLS&gt; taken from
	publisher's table. All the subscribers will receive
	modifications.</para></formalpara></listitem>

  <listitem><formalpara><title>4 - reserved</title><para /></formalpara></listitem>

  <listitem><formalpara><title>5 - ignore (D)</title>
	<para>DML operation is ignored.</para></formalpara></listitem>
</itemizedlist>

<para>Conflict resolution stops when conflict resolvers return a non-zero
value meaning that it has made a decision.</para>

<example id="ex_conflictreslntrans"><title>Conflict Resolution</title>
<para>Suppose we have the following table:</para>

<programlisting><![CDATA[
create table items(
  item_id integer primary key,

  name varchar,
  price decimal
);
]]></programlisting>

<para>"Publisher wins" 'I' conflict resolver will look like:</para>

<programlisting><![CDATA[
create procedure items_cr(
    inout _item_id integer,
    inout _name varchar,
    inout _price decimal,
    inout _origin varchar)
  returns integer
{
  return 3;
}
]]></programlisting>

<para>The conflict resolver that will make a decision based on the 
minimal price column will look like:</para>

<programlisting><![CDATA[
create procedure items_cr(
    inout _item_id integer,
    inout _name varchar,
    inout _price decimal,
    inout _rowguid varchar,
    inout _old_item_id integer,
    inout _old_name varchar,
    inout _old_price decimal,
    inout _old_rowguid varchar,
    inout _origin varchar)
  returns integer
{
  declare p decimal;
  -- get current price value
  select price into p from items where item_id = _item_id;
  if (p < _price)
    return 3;			-- publisher wins
  else if (p > _price)
    return 1;			-- subscriber wins
  return 0;			-- can't decide
}
]]></programlisting>

<para>Conflict resolver that will change the price to the minimal 
value will look like:</para>

<programlisting><![CDATA[
create procedure items_cr(
    inout _item_id integer,
    inout _name varchar,
    inout _price decimal,
    inout _rowguid varchar,
    inout _old_item_id integer,
    inout _old_name varchar,
    inout _old_price decimal,
    inout _old_rowguid varchar,
    inout _origin varchar)
  returns integer
{
  declare p decimal;
  -- get current price value
  select price into p from items where item_id = _item_id;
  if (p < _price)
    {
      _price := p;
      return 2;			-- publisher wins, change origin
    }
  return 1;			-- subscriber wins
}
]]></programlisting>
</example>

<para>Conflict resolution occurs differently for each kind of DML operation:</para>

<itemizedlist>
  <listitem><formalpara><title>INSERT</title>
	<para>When INSERT of some row with primary key &lt;PK&gt; is replayed,
	the row in the publisher's table with such &lt;PK&gt; is looked-up.
	If the row does not exist then there is no conflict, conflict 
	resolution stops and the INSERT is replayed.
	If the row exists then we have a "uniqueness conflict".  In this case 'I'
	conflict resolvers are fired-up.
	If none of the 'I' conflict resolvers were able to make a decision
	(return non-zero value) the default action is 'publisher wins'.</para>
	</formalpara></listitem>

  <listitem><formalpara><title>UPDATE</title>

	<para>When there is an UPDATE of some row with primary 
	key &lt;PK&gt; is replayed, 	the row (and its ROWGUID) in 
	publisher's table with such &lt;PK&gt; is looked-up.
	If the row does not exist then we have a "delete conflict", 
	'D' conflict resolvers are fired up.  If none of the 'D' conflict 
	resolvers were able to make a decision the default action will be 
	to 'ignore'.
	If the row exists in the publisher's table and its ROWGUID is the same
	as that from the subscriber then there is no conflict.  Conflict
	resolution stops and the UPDATE is replayed.
	If the row exists and its ROWGUID differs from the one that came
	from subscriber then we have an "update conflict".  In this case the 
	'U' conflict resolvers are fired-up.
	If none of the 'U' conflict resolvers were able to make a decision 
	(return non-zero value) the default action will be 'publisher wins'.</para>
	</formalpara></listitem>

  <listitem><formalpara><title>DELETE</title>

	<para>When DELETE of some row with primary key &lt;PK&gt; is replayed,
	the row in the publisher's table with such &lt;PK&gt; is looked-up.  
	If the row does not exist or if the row exists but its
	ROWGUID differs from the one that came from subscriber then
	we have "delete conflict".  The 'D' conflict resolvers are fired-up.  
	If none of the 'D' conflict resolvers were able to make a decision then the 
	default action will be taken to 'ignore'.
	Otherwise it is assumed that there is no conflict and DELETE statement 
	is replayed.</para>
	</formalpara></listitem>
</itemizedlist>
</sect3>

<sect3 id="bidirtransreplautoconres"><title>Automatically Generated Conflict Resolvers</title>

<para>Simple conflict resolvers can be generated automatically.
This can be done by calling REPL_ADD_CR function.</para>

<tip><title>See Also:</title>
  <para><link linkend="fn_REPL_ADD_CR"><function>REPL_ADD_CR()</function></link></para></tip>

</sect3>

<sect3 id="bidirtransrepllogdata"><title>Replication Log Data</title>

 <para>Replication log data is different for each kind of DML operation:</para>

<itemizedlist>
  <listitem><formalpara><title>INSERT</title>
	<para>(stmt, &lt;ALLCOLS&gt;)</para></formalpara></listitem>

  <listitem><formalpara><title>UPDATE</title>
	<para>(stmt, &lt;ALLCOLS&gt;, &lt;OLDPK&gt;, &lt;ALLOLDCOLS&gt;, ncols)</para></formalpara></listitem>

  <listitem><formalpara><title>DELETE</title>
	<para>(stmt, &lt;OLDPK&gt;, &lt;ALLOLDCOLS&gt;, ncols)</para></formalpara></listitem>
</itemizedlist>

<para>where</para>

<para>stmt is DML statement (varchar), &lt;ALLCOLS&gt; is new values of 
all columns, &lt;OLDPK&gt; is primary key, specifying a row for which 
(UPDATE or DELETE) DML statement is executed, &lt;ALLOLDCOLS&gt; is old 
values of all columns, ncols is number of columns in table (integer).</para>

<para>The format of the log replication data is the same as in simple transactional
replication with addition of &lt;ALLOLDCOLS&gt; and ncols for logging UPDATE and
DELETE statements.</para>
</sect3>
</sect2>