NAME

lightning-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 Lightning 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 element of the key as the plugin name (e.g. [ 'summary' ]) is recommended.
(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-replace 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.

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"
}