1.Dd January 24, 2024 2.Dt SQLITE3SESSION_ATTACH 3 3.Os 4.Sh NAME 5.Nm sqlite3session_attach 6.Nd attach a table to a session object 7.Sh SYNOPSIS 8.In sqlite3.h 9.Ft int 10.Fo sqlite3session_attach 11.Fa "sqlite3_session *pSession" 12.Fa "const char *zTab" 13.Fc 14.Sh DESCRIPTION 15If argument zTab is not NULL, then it is the name of a table to attach 16to the session object passed as the first argument. 17All subsequent changes made to the table while the session object is 18enabled will be recorded. 19See documentation for 20.Fn sqlite3session_changeset 21for further details. 22.Pp 23Or, if argument zTab is NULL, then changes are recorded for all tables 24in the database. 25If additional tables are added to the database (by executing "CREATE 26TABLE" statements) after this call is made, changes for the new tables 27are also recorded. 28.Pp 29Changes can only be recorded for tables that have a PRIMARY KEY explicitly 30defined as part of their CREATE TABLE statement. 31It does not matter if the PRIMARY KEY is an "INTEGER PRIMARY KEY" (rowid 32alias) or not. 33The PRIMARY KEY may consist of a single column, or may be a composite 34key. 35.Pp 36It is not an error if the named table does not exist in the database. 37Nor is it an error if the named table does not have a PRIMARY KEY. 38However, no changes will be recorded in either of these scenarios. 39.Pp 40Changes are not recorded for individual rows that have NULL values 41stored in one or more of their PRIMARY KEY columns. 42.Pp 43SQLITE_OK is returned if the call completes without error. 44Or, if an error occurs, an SQLite error code (e.g. SQLITE_NOMEM) is 45returned. 46.Ss Special sqlite_stat1 Handling 47As of SQLite version 3.22.0, the "sqlite_stat1" table is an exception 48to some of the rules above. 49In SQLite, the schema of sqlite_stat1 is: 50.Bd -literal 51 CREATE TABLE sqlite_stat1(tbl,idx,stat) 52.Ed 53.Pp 54Even though sqlite_stat1 does not have a PRIMARY KEY, changes are recorded 55for it as if the PRIMARY KEY is (tbl,idx). 56Additionally, changes are recorded for rows for which (idx IS NULL) 57is true. 58However, for such rows a zero-length blob (SQL value X'') is stored 59in the changeset or patchset instead of a NULL value. 60This allows such changesets to be manipulated by legacy implementations 61of sqlite3changeset_invert(), concat() and similar. 62.Pp 63The sqlite3changeset_apply() function automatically converts the zero-length 64blob back to a NULL value when updating the sqlite_stat1 table. 65However, if the application calls sqlite3changeset_new(), sqlite3changeset_old() 66or sqlite3changeset_conflict on a changeset iterator directly (including 67on a changeset iterator passed to a conflict-handler callback) then 68the X'' value is returned. 69The application must translate X'' to NULL itself if required. 70.Pp 71Legacy (older than 3.22.0) versions of the sessions module cannot capture 72changes made to the sqlite_stat1 table. 73Legacy versions of the sqlite3changeset_apply() function silently ignore 74any modifications to the sqlite_stat1 table that are part of a changeset 75or patchset. 76.Sh IMPLEMENTATION NOTES 77These declarations were extracted from the 78interface documentation at line 11101. 79.Bd -literal 80SQLITE_API int sqlite3session_attach( 81 sqlite3_session *pSession, /* Session object */ 82 const char *zTab /* Table name */ 83); 84.Ed 85.Sh SEE ALSO 86.Xr sqlite3session_changeset 3 87