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