home | help 
LIGHTNING-DATASTORE(7)					  LIGHTNING-DATASTORE(7)

NAME
     datastore -- Command for storing (plugin) data

SYNOPSIS
     datastore key [string] [hex] [mode] [generation]

DESCRIPTION
     The  datastore  RPC command allows plugins to store data in the Core Light-
     ning database, for later retrieval.

     *	key (one of): A key can either have children or  a  value,  never  both:
	parents are created and removed automatically.:
	*  (array  of strings): An array of values to form a hierarchy (though a
	   single value is treated as a one-element array). Using the first ele-
	   ment of the key as the plugin name (e.g. [  'summary'  ])  is  recom-
	   mended.
	*  (string, optional)
	*  (string)
     *	string (string, optional): Data to be saved in string format.
     *	hex (hex, optional): Data to be saved in hex format.
     *	mode  (string, optional) (one of "must-create", "must-replace", "create-
	or-replace", "must-append", "create-or-append"): Write mode to determine
	how the record is updated:
	*  must-create: fails if it already exists.
	*  must-replace: fails if it doesn't already exist.
	*  create-or-replace: never fails.
	*  must-append: must already exist, append this to what's already there.
	*  create-or-append: append if anything is there, otherwise create.  The
	   default is must-create.
     *	generation  (u64,  optional):  If  specified, means that the update will
	fail if the previously-existing data is  not  exactly  that  generation.
	This  allows for simple atomicity. This is only legal with mode must-re-
	place or must-append.

RETURN VALUE
     On success, an object is returned, containing:

     *	key (array of strings):
	*  (string, optional): Part of the key added to the datastore.
     *	generation (u64, optional): The number of times this has been updated.
     *	hex (hex, optional): The hex data which has been added to the datastore.
     *	string (string, optional): The data as a string, if it's valid utf-8.

ERRORS
     The following error codes may occur:

     *	1202: The key already exists (and mode said it must not)
     *	1203: The key does not exist (and mode said it must)
     *	1204: The generation was wrong (and generation was specified)
     *	1205: The key has children already.
     *	1206: One of the parents already exists with a value.
     *	-32602: invalid parameters

AUTHOR
     Rusty Russell rusty@rustcorp.com.au is mainly responsible.

SEE ALSO
     lightning-listdatastore(7),   lightning-deldatastore(7),	lightning-datas-
     toreusage(7)

RESOURCES
     Main web site: https://github.com/ElementsProject/lightning

EXAMPLES
     Example 1:

     Request:

     $ lightning-cli datastore -k "key"='["employee", "index"]' "string"="saving employee keys to the store" "mode"="must-create"

     {
       "id": "example:datastore#1",
       "method": "datastore",
       "params": {
	 "key": [
	   "employee",
	   "index"
	 ],
	 "string": "saving employee keys to the store",
	 "mode": "must-create"
       }
     }

     Response:

     {
       "key": [
	 "employee",
	 "index"
       ],
       "generation": 0,
       "hex": "736176696e6720656d706c6f796565206b65797320746f207468652073746f7265",
       "string": "saving employee keys to the store"
     }

     Example 2:

     Request:

     $ lightning-cli datastore -k "key"="otherkey" "string"="other" "mode"="must-create"

     {
       "id": "example:datastore#2",
       "method": "datastore",
       "params": {
	 "key": "otherkey",
	 "string": "other",
	 "mode": "must-create"
       }
     }

     Response:

     {
       "key": [
	 "otherkey"
       ],
       "generation": 0,
       "hex": "6f74686572",
       "string": "other"
     }

     Example 3:

     Request:

     $ lightning-cli datastore -k "key"="otherkey" "string"=" key: text to be appended to the otherkey" "mode"="must-append" "generation"=0

     {
       "id": "example:datastore#3",
       "method": "datastore",
       "params": {
	 "key": "otherkey",
	 "string": " key: text to be appended to the otherkey",
	 "mode": "must-append",
	 "generation": 0
       }
     }

     Response:

     {
       "key": [
	 "otherkey"
       ],
       "generation": 1,
       "hex": "6f74686572206b65793a207465787420746f20626520617070656e64656420746f20746865206f746865726b6579",
       "string": "other key: text to be appended to the otherkey"
     }

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