1.Dd January 24, 2024 2.Dt SQLITE3SESSION_DIFF 3 3.Os 4.Sh NAME 5.Nm sqlite3session_diff 6.Nd load the difference between tables into a session 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3session_diff 11.Fa "sqlite3_session *pSession" 12.Fa "const char *zFromDb" 13.Fa "const char *zTbl" 14.Fa "char **pzErrMsg" 15.Fc 16.Sh DESCRIPTION 17If it is not already attached to the session object passed as the first 18argument, this function attaches table zTbl in the same manner as the 19.Fn sqlite3session_attach 20function. 21If zTbl does not exist, or if it does not have a primary key, this 22function is a no-op (but does not return an error). 23.Pp 24Argument zFromDb must be the name of a database ("main", "temp" etc.) 25attached to the same database handle as the session object that contains 26a table compatible with the table attached to the session by this function. 27A table is considered compatible if it: 28.Bl -bullet 29.It 30Has the same name, 31.It 32Has the same set of columns declared in the same order, and 33.It 34Has the same PRIMARY KEY definition. 35.El 36.Pp 37If the tables are not compatible, SQLITE_SCHEMA is returned. 38If the tables are compatible but do not have any PRIMARY KEY columns, 39it is not an error but no changes are added to the session object. 40As with other session APIs, tables without PRIMARY KEYs are simply 41ignored. 42.Pp 43This function adds a set of changes to the session object that could 44be used to update the table in database zFrom (call this the "from-table") 45so that its content is the same as the table attached to the session 46object (call this the "to-table"). 47Specifically: 48.Bl -bullet 49.It 50For each row (primary key) that exists in the to-table but not in the 51from-table, an INSERT record is added to the session object. 52.It 53For each row (primary key) that exists in the to-table but not in the 54from-table, a DELETE record is added to the session object. 55.It 56For each row (primary key) that exists in both tables, but features 57different non-PK values in each, an UPDATE record is added to the session. 58.El 59.Pp 60To clarify, if this function is called and then a changeset constructed 61using 62.Fn sqlite3session_changeset , 63then after applying that changeset to database zFrom the contents of 64the two compatible tables would be identical. 65.Pp 66It an error if database zFrom does not exist or does not contain the 67required compatible table. 68.Pp 69If the operation is successful, SQLITE_OK is returned. 70Otherwise, an SQLite error code. 71In this case, if argument pzErrMsg is not NULL, *pzErrMsg may be set 72to point to a buffer containing an English language error message. 73It is the responsibility of the caller to free this buffer using sqlite3_free(). 74.Sh IMPLEMENTATION NOTES 75These declarations were extracted from the 76interface documentation at line 11310. 77.Bd -literal 78SQLITE_API int sqlite3session_diff( 79 sqlite3_session *pSession, 80 const char *zFromDb, 81 const char *zTbl, 82 char **pzErrMsg 83); 84.Ed 85.Sh SEE ALSO 86.Xr sqlite3session_attach 3 , 87.Xr sqlite3session_changeset 3 88