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 intermingled 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 processing 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 separate 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 modifies 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 previous 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 happened 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. Otherwise, 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 error 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, lightningd 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 database.
  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.