1.Dd January 24, 2024 2.Dt SQLITE3SESSION_CHANGESET 3 3.Os 4.Sh NAME 5.Nm sqlite3session_changeset 6.Nd generate a changeset from a session object 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3session_changeset 11.Fa "sqlite3_session *pSession" 12.Fa "int *pnChangeset" 13.Fa "void **ppChangeset" 14.Fc 15.Sh DESCRIPTION 16Obtain a changeset containing changes to the tables attached to the 17session object passed as the first argument. 18If successful, set *ppChangeset to point to a buffer containing the 19changeset and *pnChangeset to the size of the changeset in bytes before 20returning SQLITE_OK. 21If an error occurs, set both *ppChangeset and *pnChangeset to zero 22and return an SQLite error code. 23.Pp 24A changeset consists of zero or more INSERT, UPDATE and/or DELETE changes, 25each representing a change to a single row of an attached table. 26An INSERT change contains the values of each field of a new database 27row. 28A DELETE contains the original values of each field of a deleted database 29row. 30An UPDATE change contains the original values of each field of an updated 31database row along with the updated values for each updated non-primary-key 32column. 33It is not possible for an UPDATE change to represent a change that 34modifies the values of primary key columns. 35If such a change is made, it is represented in a changeset as a DELETE 36followed by an INSERT. 37.Pp 38Changes are not recorded for rows that have NULL values stored in one 39or more of their PRIMARY KEY columns. 40If such a row is inserted or deleted, no corresponding change is present 41in the changesets returned by this function. 42If an existing row with one or more NULL values stored in PRIMARY KEY 43columns is updated so that all PRIMARY KEY columns are non-NULL, only 44an INSERT is appears in the changeset. 45Similarly, if an existing row with non-NULL PRIMARY KEY values is updated 46so that one or more of its PRIMARY KEY columns are set to NULL, the 47resulting changeset contains a DELETE change only. 48.Pp 49The contents of a changeset may be traversed using an iterator created 50using the 51.Fn sqlite3changeset_start 52API. 53A changeset may be applied to a database with a compatible schema using 54the 55.Fn sqlite3changeset_apply 56API. 57.Pp 58Within a changeset generated by this function, all changes related 59to a single table are grouped together. 60In other words, when iterating through a changeset or when applying 61a changeset to a database, all changes related to a single table are 62processed before moving on to the next table. 63Tables are sorted in the same order in which they were attached (or 64auto-attached) to the sqlite3_session object. 65The order in which the changes related to a single table are stored 66is undefined. 67.Pp 68Following a successful call to this function, it is the responsibility 69of the caller to eventually free the buffer that *ppChangeset points 70to using 71.Fn sqlite3_free . 72.Ss Changeset Generation 73Once a table has been attached to a session object, the session object 74records the primary key values of all new rows inserted into the table. 75It also records the original primary key and other column values of 76any deleted or updated rows. 77For each unique primary key value, data is only recorded once - the 78first time a row with said primary key is inserted, updated or deleted 79in the lifetime of the session. 80.Pp 81There is one exception to the previous paragraph: when a row is inserted, 82updated or deleted, if one or more of its primary key columns contain 83a NULL value, no record of the change is made. 84.Pp 85The session object therefore accumulates two types of records - those 86that consist of primary key values only (created when the user inserts 87a new record) and those that consist of the primary key values and 88the original values of other table columns (created when the users 89deletes or updates a record). 90.Pp 91When this function is called, the requested changeset is created using 92both the accumulated records and the current contents of the database 93file. 94Specifically: 95.Bl -bullet 96.It 97For each record generated by an insert, the database is queried for 98a row with a matching primary key. 99If one is found, an INSERT change is added to the changeset. 100If no such row is found, no change is added to the changeset. 101.It 102For each record generated by an update or delete, the database is queried 103for a row with a matching primary key. 104If such a row is found and one or more of the non-primary key fields 105have been modified from their original values, an UPDATE change is 106added to the changeset. 107Or, if no such row is found in the table, a DELETE change is added 108to the changeset. 109If there is a row with a matching primary key in the database, but 110all fields contain their original values, no change is added to the 111changeset. 112.El 113.Pp 114This means, amongst other things, that if a row is inserted and then 115later deleted while a session object is active, neither the insert 116nor the delete will be present in the changeset. 117Or if a row is deleted and then later a row with the same primary key 118values inserted while a session object is active, the resulting changeset 119will contain an UPDATE change instead of a DELETE and an INSERT. 120.Pp 121When a session object is disabled (see the 122.Fn sqlite3session_enable 123API), it does not accumulate records when rows are inserted, updated 124or deleted. 125This may appear to have some counter-intuitive effects if a single 126row is written to more than once during a session. 127For example, if a row is inserted while a session object is enabled, 128then later deleted while the same session object is disabled, no INSERT 129record will appear in the changeset, even though the delete took place 130while the session was disabled. 131Or, if one field of a row is updated while a session is disabled, and 132another field of the same row is updated while the session is enabled, 133the resulting changeset will contain an UPDATE change that updates 134both fields. 135.Sh IMPLEMENTATION NOTES 136These declarations were extracted from the 137interface documentation at line 11183. 138.Bd -literal 139SQLITE_API int sqlite3session_changeset( 140 sqlite3_session *pSession, /* Session object */ 141 int *pnChangeset, /* OUT: Size of buffer at *ppChangeset */ 142 void **ppChangeset /* OUT: Buffer containing changeset */ 143); 144.Ed 145.Sh SEE ALSO 146.Xr sqlite3_malloc 3 , 147.Xr sqlite3changeset_apply 3 , 148.Xr sqlite3changeset_start 3 , 149.Xr sqlite3session_enable 3 150