1.Dd January 24, 2024 2.Dt SQLITE3_REBASER 3 3.Os 4.Sh NAME 5.Nm sqlite3_rebaser 6.Nd rebasing changesets 7.Sh SYNOPSIS 8.In sqlite3.h 9.Vt typedef struct sqlite3_rebaser sqlite3_rebaser; 10.Sh DESCRIPTION 11Suppose there is a site hosting a database in state S0. 12And that modifications are made that move that database to state S1 13and a changeset recorded (the "local" changeset). 14Then, a changeset based on S0 is received from another site (the "remote" 15changeset) and applied to the database. 16The database is then in state (S1+"remote"), where the exact state 17depends on any conflict resolution decisions (OMIT or REPLACE) made 18while applying "remote". 19Rebasing a changeset is to update it to take those conflict resolution 20decisions into account, so that the same conflicts do not have to be 21resolved elsewhere in the network. 22.Pp 23For example, if both the local and remote changesets contain an INSERT 24of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)": 25.Pp 26local: INSERT INTO t1 VALUES(1, 'v1'); remote: INSERT INTO t1 VALUES(1, 27\&'v2'); 28.Pp 29and the conflict resolution is REPLACE, then the INSERT change is removed 30from the local changeset (it was overridden). 31Or, if the conflict resolution was "OMIT", then the local changeset 32is modified to instead contain: 33.Pp 34UPDATE t1 SET b = 'v2' WHERE a=1; 35.Pp 36Changes within the local changeset are rebased as follows: 37.Bl -tag -width Ds 38.It Local INSERT 39This may only conflict with a remote INSERT. 40If the conflict resolution was OMIT, then add an UPDATE change to the 41rebased changeset. 42Or, if the conflict resolution was REPLACE, add nothing to the rebased 43changeset. 44.It Local DELETE 45This may conflict with a remote UPDATE or DELETE. 46In both cases the only possible resolution is OMIT. 47If the remote operation was a DELETE, then add no change to the rebased 48changeset. 49If the remote operation was an UPDATE, then the old.* fields of change 50are updated to reflect the new.* values in the UPDATE. 51.It Local UPDATE 52This may conflict with a remote UPDATE or DELETE. 53If it conflicts with a DELETE, and the conflict resolution was OMIT, 54then the update is changed into an INSERT. 55Any undefined values in the new.* record from the update change are 56filled in using the old.* values from the conflicting DELETE. 57Or, if the conflict resolution was REPLACE, the UPDATE change is simply 58omitted from the rebased changeset. 59.Pp 60If conflict is with a remote UPDATE and the resolution is OMIT, then 61the old.* values are rebased using the new.* values in the remote change. 62Or, if the resolution is REPLACE, then the change is copied into the 63rebased changeset with updates to columns also updated by the conflicting 64remote UPDATE removed. 65If this means no columns would be updated, the change is omitted. 66.El 67.Pp 68A local change may be rebased against multiple remote changes simultaneously. 69If a single key is modified by multiple remote changesets, they are 70combined as follows before the local changeset is rebased: 71.Bl -bullet 72.It 73If there has been one or more REPLACE resolutions on a key, it is rebased 74according to a REPLACE. 75.It 76If there have been no REPLACE resolutions on a key, then the local 77changeset is rebased according to the most recent of the OMIT resolutions. 78.El 79.Pp 80Note that conflict resolutions from multiple remote changesets are 81combined on a per-field basis, not per-row. 82This means that in the case of multiple remote UPDATE operations, some 83fields of a single local change may be rebased for REPLACE while others 84are rebased for OMIT. 85.Pp 86In order to rebase a local changeset, the remote changeset must first 87be applied to the local database using sqlite3changeset_apply_v2() 88and the buffer of rebase information captured. 89Then: 90.Bl -enum 91.It 92An sqlite3_rebaser object is created by calling sqlite3rebaser_create(). 93.It 94The new object is configured with the rebase buffer obtained from sqlite3changeset_apply_v2() 95by calling sqlite3rebaser_configure(). 96If the local changeset is to be rebased against multiple remote changesets, 97then sqlite3rebaser_configure() should be called multiple times, in 98the same order that the multiple sqlite3changeset_apply_v2() calls 99were made. 100.It 101Each local changeset is rebased by calling sqlite3rebaser_rebase(). 102.It 103The sqlite3_rebaser object is deleted by calling sqlite3rebaser_delete(). 104.El 105.Pp 106.Sh IMPLEMENTATION NOTES 107These declarations were extracted from the 108interface documentation at line 12352. 109.Bd -literal 110typedef struct sqlite3_rebaser sqlite3_rebaser; 111.Ed 112