1.Dd January 24, 2024 2.Dt SQLITE3CHANGEGROUP_ADD 3 3.Os 4.Sh NAME 5.Nm sqlite3changegroup_add 6.Nd add a changeset to a changegroup 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3changegroup_add 11.Fa "sqlite3_changegroup*" 12.Fa "int nData" 13.Fa "void *pData" 14.Fc 15.Sh DESCRIPTION 16Add all changes within the changeset (or patchset) in buffer pData 17(size nData bytes) to the changegroup. 18.Pp 19If the buffer contains a patchset, then all prior calls to this function 20on the same changegroup object must also have specified patchsets. 21Or, if the buffer contains a changeset, so must have the earlier calls 22to this function. 23Otherwise, SQLITE_ERROR is returned and no changes are added to the 24changegroup. 25.Pp 26Rows within the changeset and changegroup are identified by the values 27in their PRIMARY KEY columns. 28A change in the changeset is considered to apply to the same row as 29a change already present in the changegroup if the two rows have the 30same primary key. 31.Pp 32Changes to rows that do not already appear in the changegroup are simply 33copied into it. 34Or, if both the new changeset and the changegroup contain changes that 35apply to a single row, the final contents of the changegroup depends 36on the type of each change, as follows: 37.Pp 38 Existing Change New Change Output Change 39 INSERT INSERT The new change is ignored. 40This case does not occur if the new changeset was recorded immediately 41after the changesets already added to the changegroup. 42 INSERT UPDATE The INSERT change remains in the changegroup. 43The values in the INSERT change are modified as if the row was inserted 44by the existing change and then updated according to the new change. 45 INSERT DELETE The existing INSERT is removed from the changegroup. 46The DELETE is not added. 47 UPDATE INSERT The new change is ignored. 48This case does not occur if the new changeset was recorded immediately 49after the changesets already added to the changegroup. 50 UPDATE UPDATE The existing UPDATE remains within the changegroup. 51It is amended so that the accompanying values are as if the row was 52updated once by the existing change and then again by the new change. 53 UPDATE DELETE The existing UPDATE is replaced by the new DELETE within 54the changegroup. 55 DELETE INSERT If one or more of the column values in the row inserted 56by the new change differ from those in the row deleted by the existing 57change, the existing DELETE is replaced by an UPDATE within the changegroup. 58Otherwise, if the inserted row is exactly the same as the deleted row, 59the existing DELETE is simply discarded. 60 DELETE UPDATE The new change is ignored. 61This case does not occur if the new changeset was recorded immediately 62after the changesets already added to the changegroup. 63 DELETE DELETE The new change is ignored. 64This case does not occur if the new changeset was recorded immediately 65after the changesets already added to the changegroup. 66.Pp 67If the new changeset contains changes to a table that is already present 68in the changegroup, then the number of columns and the position of 69the primary key columns for the table must be consistent. 70If this is not the case, this function fails with SQLITE_SCHEMA. 71Except, if the changegroup object has been configured with a database 72schema using the sqlite3changegroup_schema() API, then it is possible 73to combine changesets with different numbers of columns for a single 74table, provided that they are otherwise compatible. 75.Pp 76If the input changeset appears to be corrupt and the corruption is 77detected, SQLITE_CORRUPT is returned. 78Or, if an out-of-memory condition occurs during processing, this function 79returns SQLITE_NOMEM. 80.Pp 81In all cases, if an error occurs the state of the final contents of 82the changegroup is undefined. 83If no error occurs, SQLITE_OK is returned. 84.Sh IMPLEMENTATION NOTES 85These declarations were extracted from the 86interface documentation at line 11900. 87.Bd -literal 88SQLITE_API int sqlite3changegroup_add(sqlite3_changegroup*, int nData, void *pData); 89.Ed 90