1.Dd December 19, 2018 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.Nd The pre-update hook. 11.Sh SYNOPSIS 12.Ft void * 13.Fo sqlite3_preupdate_hook 14.Fa "sqlite3 *db" 15.Fa "void(*xPreUpdate)( void *pCtx, sqlite3 *db, int op, char const *zDb, char const *zName, sqlite3_int64 iKey1, sqlite3_int64 iKey2 )" 16.Fa "void* " 17.Fc 18.Ft int 19.Fo sqlite3_preupdate_old 20.Fa "sqlite3 *" 21.Fa "int" 22.Fa "sqlite3_value **" 23.Fc 24.Ft int 25.Fo sqlite3_preupdate_count 26.Fa "sqlite3 *" 27.Fc 28.Ft int 29.Fo sqlite3_preupdate_depth 30.Fa "sqlite3 *" 31.Fc 32.Ft int 33.Fo sqlite3_preupdate_new 34.Fa "sqlite3 *" 35.Fa "int" 36.Fa "sqlite3_value **" 37.Fc 38.Sh DESCRIPTION 39These interfaces are only available if SQLite is compiled using the 40SQLITE_ENABLE_PREUPDATE_HOOK compile-time 41option. 42.Pp 43The sqlite3_preupdate_hook() interface registers 44a callback function that is invoked prior to each INSERT, UPDATE, 45and DELETE operation on a database table. 46At most one preupdate hook may be registered at a time on a single 47database connection; each call to sqlite3_preupdate_hook() 48overrides the previous setting. 49The preupdate hook is disabled by invoking sqlite3_preupdate_hook() 50with a NULL pointer as the second parameter. 51The third parameter to sqlite3_preupdate_hook() 52is passed through as the first parameter to callbacks. 53.Pp 54The preupdate hook only fires for changes to real database tables; 55the preupdate hook is not invoked for changes to virtual tables 56or to system tables like sqlite_master or sqlite_stat1. 57.Pp 58The second parameter to the preupdate callback is a pointer to the 59database connection that registered the preupdate 60hook. 61The third parameter to the preupdate callback is one of the constants 62SQLITE_INSERT, SQLITE_DELETE, or SQLITE_UPDATE 63to identify the kind of update operation that is about to occur. 64The fourth parameter to the preupdate callback is the name of the database 65within the database connection that is being modified. 66This will be "main" for the main database or "temp" for TEMP tables 67or the name given after the AS keyword in the ATTACH statement 68for attached databases. 69The fifth parameter to the preupdate callback is the name of the table 70that is being modified. 71.Pp 72For an UPDATE or DELETE operation on a rowid table, the 73sixth parameter passed to the preupdate callback is the initial rowid 74of the row being modified or deleted. 75For an INSERT operation on a rowid table, or any operation on a WITHOUT 76ROWID table, the value of the sixth parameter is undefined. 77For an INSERT or UPDATE on a rowid table the seventh parameter is the 78final rowid value of the row being inserted or updated. 79The value of the seventh parameter passed to the callback function 80is not defined for operations on WITHOUT ROWID tables, or for INSERT 81operations on rowid tables. 82.Pp 83The sqlite3_preupdate_old(), sqlite3_preupdate_new(), 84sqlite3_preupdate_count(), and sqlite3_preupdate_depth() 85interfaces provide additional information about a preupdate event. 86These routines may only be called from within a preupdate callback. 87Invoking any of these routines from outside of a preupdate callback 88or with a database connection pointer that is different 89from the one supplied to the preupdate callback results in undefined 90and probably undesirable behavior. 91.Pp 92The sqlite3_preupdate_count(D) interface 93returns the number of columns in the row that is being inserted, updated, 94or deleted. 95.Pp 96The sqlite3_preupdate_old(D,N,P) interface 97writes into P a pointer to a protected sqlite3_value 98that contains the value of the Nth column of the table row before it 99is updated. 100The N parameter must be between 0 and one less than the number of columns 101or the behavior will be undefined. 102This must only be used within SQLITE_UPDATE and SQLITE_DELETE preupdate 103callbacks; if it is used by an SQLITE_INSERT callback then the behavior 104is undefined. 105The sqlite3_value that P points to will be destroyed when 106the preupdate callback returns. 107.Pp 108The sqlite3_preupdate_new(D,N,P) interface 109writes into P a pointer to a protected sqlite3_value 110that contains the value of the Nth column of the table row after it 111is updated. 112The N parameter must be between 0 and one less than the number of columns 113or the behavior will be undefined. 114This must only be used within SQLITE_INSERT and SQLITE_UPDATE preupdate 115callbacks; if it is used by an SQLITE_DELETE callback then the behavior 116is undefined. 117The sqlite3_value that P points to will be destroyed when 118the preupdate callback returns. 119.Pp 120The sqlite3_preupdate_depth(D) interface 121returns 0 if the preupdate callback was invoked as a result of a direct 122insert, update, or delete operation; or 1 for inserts, updates, or 123deletes invoked by top-level triggers; or 2 for changes resulting from 124triggers called by top-level triggers; and so forth. 125.Pp 126.Sh SEE ALSO 127.Xr sqlite3 3 , 128.Xr sqlite3_value 3 , 129.Xr sqlite3_preupdate_hook 3 , 130.Xr sqlite3_update_hook 3 , 131.Xr sqlite3_value 3 , 132.Xr SQLITE_CREATE_INDEX 3 133