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