doc: document the current limitations of the db_write hook.

In theory we could allow a db_write-using plugin to have other
hooks/commands by embargoing their other responses until the exclusive
period is over.  That would be nice for a 'dbmirrorinfo' command, for
example.

The other option would be to *always* go exclusive on a db_write-using
plugin, so responses can never get intermingled.

Signed-off-by: Rusty Russell <[email protected]>

doc/PLUGINS.md

@@ -16,8 +16,6 @@ variety of ways:
    internal events in `lightningd` and alter its behavior or inject
    custom behaviors.
 
-*Note: Hooks are not yet implemented, and the API is under active development.*
-
 A plugin may be written in any language, and communicates with
 `lightningd` through the plugin's `stdin` and `stdout`. JSON-RPCv2 is
 used as protocol on top of the two streams, with the plugin acting as
@@ -270,5 +268,25 @@ gossiped list of known addresses. In particular this means that the port for
 incoming connections is an ephemeral port, that may not be available for
 reconnections.
 
+#### `db_write`
+
+This hook is called whenever a change is about to be committed to the database.
+It is currently extremely restricted:
+
+1. a plugin registering for this hook should not perform anything that may cause
+   a db 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!
+
+```json
+{
+  "writes": [ "PRAGMA foreign_keys = ON" ]
+}
+```
+
+Any response but "true" will cause lightningd to error without
+committing to the database!
+
 [jsonrpc-spec]: https://www.jsonrpc.org/specification
 [jsonrpc-notification-spec]: https://www.jsonrpc.org/specification#notification