.Dd December 19, 2018
.Dt SQLITE3_REBASER 3
.Os
.Sh NAME
.Nm sqlite3_rebaser
.Nd Rebasing changesets
.Sh SYNOPSIS
.Vt typedef struct sqlite3_rebaser sqlite3_rebaser;
.Sh DESCRIPTION
Suppose there is a site hosting a database in state S0.
And that modifications are made that move that database to state S1
and a changeset recorded (the "local" changeset).
Then, a changeset based on S0 is received from another site (the "remote"
changeset) and applied to the database.
The database is then in state (S1+"remote"), where the exact state
depends on any conflict resolution decisions (OMIT or REPLACE) made
while applying "remote".
Rebasing a changeset is to update it to take those conflict resolution
decisions into account, so that the same conflicts do not have to be
resolved elsewhere in the network.
.Pp
For example, if both the local and remote changesets contain an INSERT
of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)": 
.Pp
local:  INSERT INTO t1 VALUES(1, 'v1'); remote: INSERT INTO t1 VALUES(1,
'v2'); 
.Pp
and the conflict resolution is REPLACE, then the INSERT change is removed
from the local changeset (it was overridden).
Or, if the conflict resolution was "OMIT", then the local changeset
is modified to instead contain: 
.Pp
UPDATE t1 SET b = 'v2' WHERE a=1; 
.Pp
Changes within the local changeset are rebased as follows: 
.Bl -tag -width Ds
.It Local INSERTThis may only conflict with a remote INSERT.
If the conflict resolution was OMIT, then add an UPDATE change to the
rebased changeset.
Or, if the conflict resolution was REPLACE, add nothing to the rebased
changeset.
.It Local DELETEThis may conflict with a remote UPDATE or DELETE.
In both cases the only possible resolution is OMIT.
If the remote operation was a DELETE, then add no change to the rebased
changeset.
If the remote operation was an UPDATE, then the old.* fields of change
are updated to reflect the new.* values in the UPDATE.
.It Local UPDATEThis may conflict with a remote UPDATE or DELETE.
If it conflicts with a DELETE, and the conflict resolution was OMIT,
then the update is changed into an INSERT.
Any undefined values in the new.* record from the update change are
filled in using the old.* values from the conflicting DELETE.
Or, if the conflict resolution was REPLACE, the UPDATE change is simply
omitted from the rebased changeset.
.Pp
If conflict is with a remote UPDATE and the resolution is OMIT, then
the old.* values are rebased using the new.* values in the remote change.
Or, if the resolution is REPLACE, then the change is copied into the
rebased changeset with updates to columns also updated by the conflicting
remote UPDATE removed.
If this means no columns would be updated, the change is omitted.
.El
.Pp
A local change may be rebased against multiple remote changes simultaneously.
If a single key is modified by multiple remote changesets, they are
combined as follows before the local changeset is rebased: 
.Bl -bullet
.It
If there has been one or more REPLACE resolutions on a key, it is rebased
according to a REPLACE.
.It
If there have been no REPLACE resolutions on a key, then the local
changeset is rebased according to the most recent of the OMIT resolutions.
.El
.Pp
Note that conflict resolutions from multiple remote changesets are
combined on a per-field basis, not per-row.
This means that in the case of multiple remote UPDATE operations, some
fields of a single local change may be rebased for REPLACE while others
are rebased for OMIT.
.Pp
In order to rebase a local changeset, the remote changeset must first
be applied to the local database using sqlite3changeset_apply_v2()
and the buffer of rebase information captured.
Then: 
.Bl -enum
.It
An sqlite3_rebaser object is created by calling sqlite3rebaser_create().
.It
The new object is configured with the rebase buffer obtained from sqlite3changeset_apply_v2()
by calling sqlite3rebaser_configure().
If the local changeset is to be rebased against multiple remote changesets,
then sqlite3rebaser_configure() should be called multiple times, in
the same order that the multiple sqlite3changeset_apply_v2() calls
were made.
.It
Each local changeset is rebased by calling sqlite3rebaser_rebase().
.It
The sqlite3_rebaser object is deleted by calling sqlite3rebaser_delete().
.El
.Pp