1.Dd $Mdocdate$ 2.Dt SQLITE3CHANGESET_APPLY 3 3.Os 4.Sh NAME 5.Nm sqlite3changeset_apply 6.Nd Apply A Changeset To A Database 7.Sh SYNOPSIS 8.Ft int 9.Fo sqlite3changeset_apply 10.Fa "sqlite3 *db" 11.Fa "int nChangeset" 12.Fa "void *pChangeset" 13.Fa "int(*xFilter)( void *pCtx, const char *zTab )" 14.Fa "int(*xConflict)( void *pCtx, int eConflict, sqlite3_changeset_iter *p )" 15.Fa "void *pCtx " 16.Fc 17.Sh DESCRIPTION 18Apply a changeset to a database. 19This function attempts to update the "main" database attached to handle 20db with the changes found in the changeset passed via the second and 21third arguments. 22.Pp 23The fourth argument (xFilter) passed to this function is the "filter 24callback". 25If it is not NULL, then for each table affected by at least one change 26in the changeset, the filter callback is invoked with the table name 27as the second argument, and a copy of the context pointer passed as 28the sixth argument to this function as the first. 29If the "filter callback" returns zero, then no attempt is made to apply 30any changes to the table. 31Otherwise, if the return value is non-zero or the xFilter argument 32to this function is NULL, all changes related to the table are attempted. 33.Pp 34For each table that is not excluded by the filter callback, this function 35tests that the target database contains a compatible table. 36A table is considered compatible if all of the following are true: 37.Bl -bullet 38.It 39The table has the same name as the name recorded in the changeset, 40and 41.It 42The table has the same number of columns as recorded in the changeset, 43and 44.It 45The table has primary key columns in the same position as recorded 46in the changeset. 47.El 48.Pp 49If there is no compatible table, it is not an error, but none of the 50changes associated with the table are applied. 51A warning message is issued via the sqlite3_log() mechanism with the 52error code SQLITE_SCHEMA. 53At most one such warning is issued for each table in the changeset. 54.Pp 55For each change for which there is a compatible table, an attempt is 56made to modify the table contents according to the UPDATE, INSERT or 57DELETE change. 58If a change cannot be applied cleanly, the conflict handler function 59passed as the fifth argument to sqlite3changeset_apply() may be invoked. 60A description of exactly when the conflict handler is invoked for each 61type of change is below. 62.Pp 63Unlike the xFilter argument, xConflict may not be passed NULL. 64The results of passing anything other than a valid function pointer 65as the xConflict argument are undefined. 66.Pp 67Each time the conflict handler function is invoked, it must return 68one of SQLITE_CHANGESET_OMIT, SQLITE_CHANGESET_ABORT 69or SQLITE_CHANGESET_REPLACE. 70SQLITE_CHANGESET_REPLACE may only be returned if the second argument 71passed to the conflict handler is either SQLITE_CHANGESET_DATA or SQLITE_CHANGESET_CONFLICT. 72If the conflict-handler returns an illegal value, any changes already 73made are rolled back and the call to sqlite3changeset_apply() returns 74SQLITE_MISUSE. 75Different actions are taken by sqlite3changeset_apply() depending on 76the value returned by each invocation of the conflict-handler function. 77Refer to the documentation for the three available return values 78for details. 79.Bl -tag -width Ds 80.It DELETE ChangesFor each DELETE change, this function checks if the 81target database contains a row with the same primary key value (or 82values) as the original row values stored in the changeset. 83If it does, and the values stored in all non-primary key columns also 84match the values stored in the changeset the row is deleted from the 85target database. 86.Pp 87If a row with matching primary key values is found, but one or more 88of the non-primary key fields contains a value different from the original 89row value stored in the changeset, the conflict-handler function is 90invoked with SQLITE_CHANGESET_DATA as the second 91argument. 92.Pp 93If no row with matching primary key values is found in the database, 94the conflict-handler function is invoked with SQLITE_CHANGESET_NOTFOUND 95passed as the second argument. 96.Pp 97If the DELETE operation is attempted, but SQLite returns SQLITE_CONSTRAINT 98(which can only happen if a foreign key constraint is violated), the 99conflict-handler function is invoked with SQLITE_CHANGESET_CONSTRAINT 100passed as the second argument. 101This includes the case where the DELETE operation is attempted because 102an earlier call to the conflict handler function returned SQLITE_CHANGESET_REPLACE. 103.It INSERT ChangesFor each INSERT change, an attempt is made to insert 104the new row into the database. 105.Pp 106If the attempt to insert the row fails because the database already 107contains a row with the same primary key values, the conflict handler 108function is invoked with the second argument set to SQLITE_CHANGESET_CONFLICT. 109.Pp 110If the attempt to insert the row fails because of some other constraint 111violation (e.g. 112NOT NULL or UNIQUE), the conflict handler function is invoked with 113the second argument set to SQLITE_CHANGESET_CONSTRAINT. 114This includes the case where the INSERT operation is re-attempted because 115an earlier call to the conflict handler function returned SQLITE_CHANGESET_REPLACE. 116.It UPDATE ChangesFor each UPDATE change, this function checks if the 117target database contains a row with the same primary key value (or 118values) as the original row values stored in the changeset. 119If it does, and the values stored in all non-primary key columns also 120match the values stored in the changeset the row is updated within 121the target database. 122.Pp 123If a row with matching primary key values is found, but one or more 124of the non-primary key fields contains a value different from an original 125row value stored in the changeset, the conflict-handler function is 126invoked with SQLITE_CHANGESET_DATA as the second 127argument. 128Since UPDATE changes only contain values for non-primary key fields 129that are to be modified, only those fields need to match the original 130values to avoid the SQLITE_CHANGESET_DATA conflict-handler callback. 131.Pp 132If no row with matching primary key values is found in the database, 133the conflict-handler function is invoked with SQLITE_CHANGESET_NOTFOUND 134passed as the second argument. 135.Pp 136If the UPDATE operation is attempted, but SQLite returns SQLITE_CONSTRAINT, 137the conflict-handler function is invoked with SQLITE_CHANGESET_CONSTRAINT 138passed as the second argument. 139This includes the case where the UPDATE operation is attempted after 140an earlier call to the conflict handler function returned SQLITE_CHANGESET_REPLACE. 141.El 142.Pp 143It is safe to execute SQL statements, including those that write to 144the table that the callback related to, from within the xConflict callback. 145This can be used to further customize the applications conflict resolution 146strategy. 147.Pp 148All changes made by this function are enclosed in a savepoint transaction. 149If any other error (aside from a constraint failure when attempting 150to write to the target database) occurs, then the savepoint transaction 151is rolled back, restoring the target database to its original state, 152and an SQLite error code returned. 153.Sh SEE ALSO 154.Xr SQLITE_CHANGESET_OMIT 3 , 155.Xr SQLITE_CHANGESET_DATA 3 , 156.Xr SQLITE_CHANGESET_OMIT 3 157