home | help 
LIGHTNING-HOOK-DB_WRITE(7)			      LIGHTNING-HOOK-DB_WRITE(7)

NAME
     db_write -- Hook fired before database writes are committed

DESCRIPTION
     The  db_write  hook is called whenever a change is about to be committed to
     the database, if you are using a SQLITE3 database (the default).  This hook
     will be useless (the "writes" field will always be empty) if you are  using
     a PostgreSQL database.

     This  hook  is  extremely restricted: 1. A plugin registering for this hook
     should not perform anything that may cause a database operation in response
     (pretty much, anything but logging).  2. A plugin registering for this hook
     should not register for other hooks or commands, as these may become inter-
     mingled and break rule #1.  3. The hook will be called before  your  plugin
     is initialized!

     This hook is strongly synchronous: lightningd will halt almost all process-
     ing until all plugins have responded.

     This  hook  is intended for creating continuous backups. The intent is that
     your backup plugin maintains three pieces of information (possibly in sepa-
     rate files): 1. A snapshot of the database 2. A  log  of  database  queries
     that will bring that snapshot up-to-date 3. The previous data_version

     data_version  is  an unsigned 32-bit number that will always increment by 1
     each time db_write is called. Note that this will wrap around on the  limit
     of 32-bit numbers.

     writes is an array of strings, each string being a database query that mod-
     ifies the database.  If the data_version above is validated correctly, then
     you can simply append this to the log of database queries.

     Your  plugin MUST validate the data_version. It MUST keep track of the pre-
     vious data_version it got, and: 1. If the new data_version is  exactly  one
     higher  than the previous, then this is the ideal case and nothing bad hap-
     pened and we should save this and continue.  2. If the new data_version  is
     exactly  the  same  value as the previous, then the previous set of queries
     was not committed.  Your plugin MAY overwrite the previous set  of  queries
     with  the	current  set,  or  it MAY overwrite its entire backup with a new
     snapshot of the database and the current writes array (treating  this  case
     as  if  data_version were two or more higher than the previous).  3. If the
     new data_version is less than the previous, your plugin MUST halt and catch
     fire, and have the operator inspect what exactly happened here.  4.  Other-
     wise,  some  queries were lost and your plugin SHOULD recover by creating a
     new snapshot of the database: copy the database file,  back  up  the  given
     writes  array,  then delete (or atomically rename if in a POSIX filesystem)
     the previous backups of the database and SQL statements, or  you  MAY  fail
     the hook to abort lightningd.

     The  "rolling up" of the database could be done periodically as well if the
     log of SQL statements has grown large.

     Any response other than {"result": "continue"} will cause lightningd to er-
     ror without committing to the database! This is the expected  way	to  halt
     and catch fire.

     db_write  is  a  parallel-chained hook, i.e., multiple plugins can register
     it, and all of them will be invoked simultaneously without regard for order
     of registration.  The hook is considered handled if all registered  plugins
     return  {"result": "continue"}. If any plugin returns anything else, light-
     ningd will error without committing to the database.

HOOK PAYLOAD
     *	data_version (u32): A monotonically increasing 32-bit  unsigned  integer
	representing the database version.  Wraps around at the 32-bit limit.
     *	writes (array of strings): Array of SQL statements that modify the data-
	base.  If using PostgreSQL, this array will always be empty.  Each entry
	is a SQL query string.:
	*  (string, optional)

HOOK RETURN
     *	result (string) (always "continue"): Must be "continue" for the database
	commit	to  proceed.   Any  other  value will abort the commit and cause
	lightningd to error.

Core Lightning v26.06.1 			      LIGHTNING-HOOK-DB_WRITE(7)
home | help