1.Dd January 24, 2024 2.Dt SQLITE3_PREUPDATE_HOOK 3 3.Os 4.Sh NAME 5.Nm sqlite3_preupdate_hook , 6.Nm sqlite3_preupdate_old , 7.Nm sqlite3_preupdate_count , 8.Nm sqlite3_preupdate_depth , 9.Nm sqlite3_preupdate_new , 10.Nm sqlite3_preupdate_blobwrite 11.Nd the pre-update hook 12.Sh SYNOPSIS 13.In sqlite3.h 14.Ft void * 15.Fo sqlite3_preupdate_hook 16.Fa "sqlite3 *db" 17.Fa "void(*xPreUpdate)( void *pCtx,sqlite3 *db,int op,char const *zDb,char const *zName,sqlite3_int64 iKey1,sqlite3_int64 iKey2)" 18.Fa "void*" 19.Fc 20.Ft int 21.Fo sqlite3_preupdate_old 22.Fa "sqlite3 *" 23.Fa "int" 24.Fa "sqlite3_value **" 25.Fc 26.Ft int 27.Fo sqlite3_preupdate_count 28.Fa "sqlite3 *" 29.Fc 30.Ft int 31.Fo sqlite3_preupdate_depth 32.Fa "sqlite3 *" 33.Fc 34.Ft int 35.Fo sqlite3_preupdate_new 36.Fa "sqlite3 *" 37.Fa "int" 38.Fa "sqlite3_value **" 39.Fc 40.Ft int 41.Fo sqlite3_preupdate_blobwrite 42.Fa "sqlite3 *" 43.Fc 44.Sh DESCRIPTION 45These interfaces are only available if SQLite is compiled using the 46SQLITE_ENABLE_PREUPDATE_HOOK compile-time 47option. 48.Pp 49The 50.Fn sqlite3_preupdate_hook 51interface registers a callback function that is invoked prior to each 52INSERT, UPDATE, and DELETE operation on a database 53table. 54At most one preupdate hook may be registered at a time on a single 55database connection; each call to 56.Fn sqlite3_preupdate_hook 57overrides the previous setting. 58The preupdate hook is disabled by invoking 59.Fn sqlite3_preupdate_hook 60with a NULL pointer as the second parameter. 61The third parameter to 62.Fn sqlite3_preupdate_hook 63is passed through as the first parameter to callbacks. 64.Pp 65The preupdate hook only fires for changes to real database tables; 66the preupdate hook is not invoked for changes to virtual tables 67or to system tables like sqlite_sequence or sqlite_stat1. 68.Pp 69The second parameter to the preupdate callback is a pointer to the 70database connection that registered the preupdate 71hook. 72The third parameter to the preupdate callback is one of the constants 73SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE 74to identify the kind of update operation that is about to occur. 75The fourth parameter to the preupdate callback is the name of the database 76within the database connection that is being modified. 77This will be "main" for the main database or "temp" for TEMP tables 78or the name given after the AS keyword in the ATTACH statement 79for attached databases. 80The fifth parameter to the preupdate callback is the name of the table 81that is being modified. 82.Pp 83For an UPDATE or DELETE operation on a rowid table, the 84sixth parameter passed to the preupdate callback is the initial rowid 85of the row being modified or deleted. 86For an INSERT operation on a rowid table, or any operation on a WITHOUT 87ROWID table, the value of the sixth parameter is undefined. 88For an INSERT or UPDATE on a rowid table the seventh parameter is the 89final rowid value of the row being inserted or updated. 90The value of the seventh parameter passed to the callback function 91is not defined for operations on WITHOUT ROWID tables, or for DELETE 92operations on rowid tables. 93.Pp 94The sqlite3_preupdate_hook(D,C,P) function returns the P argument from 95the previous call on the same database connection 96D, or NULL for the first call on D. 97.Pp 98The 99.Fn sqlite3_preupdate_old , 100.Fn sqlite3_preupdate_new , 101.Fn sqlite3_preupdate_count , 102and 103.Fn sqlite3_preupdate_depth 104interfaces provide additional information about a preupdate event. 105These routines may only be called from within a preupdate callback. 106Invoking any of these routines from outside of a preupdate callback 107or with a database connection pointer that is different 108from the one supplied to the preupdate callback results in undefined 109and probably undesirable behavior. 110.Pp 111The sqlite3_preupdate_count(D) interface 112returns the number of columns in the row that is being inserted, updated, 113or deleted. 114.Pp 115The sqlite3_preupdate_old(D,N,P) interface 116writes into P a pointer to a protected sqlite3_value 117that contains the value of the Nth column of the table row before it 118is updated. 119The N parameter must be between 0 and one less than the number of columns 120or the behavior will be undefined. 121This must only be used within SQLITE_UPDATE and SQLITE_DELETE preupdate 122callbacks; if it is used by an SQLITE_INSERT callback then the behavior 123is undefined. 124The sqlite3_value that P points to will be destroyed when 125the preupdate callback returns. 126.Pp 127The sqlite3_preupdate_new(D,N,P) interface 128writes into P a pointer to a protected sqlite3_value 129that contains the value of the Nth column of the table row after it 130is updated. 131The N parameter must be between 0 and one less than the number of columns 132or the behavior will be undefined. 133This must only be used within SQLITE_INSERT and SQLITE_UPDATE preupdate 134callbacks; if it is used by an SQLITE_DELETE callback then the behavior 135is undefined. 136The sqlite3_value that P points to will be destroyed when 137the preupdate callback returns. 138.Pp 139The sqlite3_preupdate_depth(D) interface 140returns 0 if the preupdate callback was invoked as a result of a direct 141insert, update, or delete operation; or 1 for inserts, updates, or 142deletes invoked by top-level triggers; or 2 for changes resulting from 143triggers called by top-level triggers; and so forth. 144.Pp 145When the 146.Fn sqlite3_blob_write 147API is used to update a blob column, the pre-update hook is invoked 148with SQLITE_DELETE. 149This is because the in this case the new values are not available. 150In this case, when a callback made with op==SQLITE_DELETE is actually 151a write using the sqlite3_blob_write() API, the 152.Fn sqlite3_preupdate_blobwrite 153returns the index of the column being written. 154In other cases, where the pre-update hook is being invoked for some 155other reason, including a regular DELETE, sqlite3_preupdate_blobwrite() 156returns -1. 157.Pp 158.Sh IMPLEMENTATION NOTES 159These declarations were extracted from the 160interface documentation at line 10316. 161.Bd -literal 162#if defined(SQLITE_ENABLE_PREUPDATE_HOOK) 163SQLITE_API void *sqlite3_preupdate_hook( 164 sqlite3 *db, 165 void(*xPreUpdate)( 166 void *pCtx, /* Copy of third arg to preupdate_hook() */ 167 sqlite3 *db, /* Database handle */ 168 int op, /* SQLITE_UPDATE, DELETE or INSERT */ 169 char const *zDb, /* Database name */ 170 char const *zName, /* Table name */ 171 sqlite3_int64 iKey1, /* Rowid of row about to be deleted/updated */ 172 sqlite3_int64 iKey2 /* New rowid value (for a rowid UPDATE) */ 173 ), 174 void* 175); 176SQLITE_API int sqlite3_preupdate_old(sqlite3 *, int, sqlite3_value **); 177SQLITE_API int sqlite3_preupdate_count(sqlite3 *); 178SQLITE_API int sqlite3_preupdate_depth(sqlite3 *); 179SQLITE_API int sqlite3_preupdate_new(sqlite3 *, int, sqlite3_value **); 180SQLITE_API int sqlite3_preupdate_blobwrite(sqlite3 *); 181#endif 182.Ed 183.Sh SEE ALSO 184.Xr sqlite3 3 , 185.Xr sqlite3_blob_write 3 , 186.Xr sqlite3_update_hook 3 , 187.Xr sqlite3_value 3 , 188.Xr SQLITE_CREATE_INDEX 3 189