aljaz/lightning
1
0
Fork 0
mirror of https://github.com/aljazceru/lightning.git synced 2025-12-19 23:24:27 +01:00
Code Issues Packages Projects Releases Wiki Activity

doc/PLUGINS.md: Mention data_version field of db_write, sketch how the backup plugin should work.

Browse Source 
ChangeLog-Added: Fully documented `db_write` hooks in `doc/PLUGINS.md`.
This commit is contained in:
ZmnSCPxj jxPCSnmZ
2020-01-29 17:02:31 +08:00
committed by Christian Decker
parent d2638c99af
commit 9346043f94
1 changed files with 50 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
doc/PLUGINS.md
View File

@@ -514,16 +514,66 @@ It is currently extremely restricted:
commands, as these may become intermingled and break rule #1. commands, as these may become intermingled and break rule #1.
3. the hook will be called before your plugin is initialized! 3. the hook will be called before your plugin is initialized!
This hook, unlike all the other hooks, is also strongly synchronous:
`lightningd` will stop almost all the other processing until this
hook responds.
```json ```json
{ {
"data_version": 42,
"writes": [ "writes": [
"PRAGMA foreign_keys = ON" "PRAGMA foreign_keys = ON"
] ]
} }
``` ```
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, and (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 happend 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 but "true" will cause lightningd to error without Any response but "true" will cause lightningd to error without
committing to the database! committing to the database!
This is the expected way to halt and catch fire.
#### `invoice_payment` #### `invoice_payment`