.TH "LIGHTNING-DATASTORE" "7" "" "" "lightning-datastore"
.SH NAME
lightning-datastore - Command for storing (plugin) data
.SH SYNOPSIS

\fBdatastore\fR \fIkey\fR [\fIstring\fR] [\fIhex\fR] [\fImode\fR] [\fIgeneration\fR]

.SH DESCRIPTION

The \fBdatastore\fR RPC command allows plugins to store data in the
c-lightning database, for later retrieval\.


There can only be one entry for each \fIkey\fR, so prefixing with the
plugin name (e\.g\. \fBsummary.\fR) is recommended\.


\fImode\fR is one of "must-create" (default, fails it it already exists),
"must-replace" (fails it it doesn't already exist),
"create-or-replace" (never fails), "must-append" (must already exist,
append this to what's already there) or "create-or-append" (append if
anything is there, otherwise create)\.


\fIgeneration\fR, 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 \fImode\fR "must-replace"
or "must-append"\.

.SH RETURN VALUE

On success, an object is returned, containing:

.RS
.IP \[bu]
\fBkey\fR (string): The key which has been added to the datastore
.IP \[bu]
\fBgeneration\fR (u64): The number of times this has been updated
.IP \[bu]
\fBhex\fR (hex): The hex data which has been added to the datastore
.IP \[bu]
\fBstring\fR (string, optional): The data as a string, if it's valid utf-8

.RE

The following error codes may occur:

.RS
.IP \[bu]
1202: The key already exists (and mode said it must not)
.IP \[bu]
1203: The key does not exist (and mode said it must)
.IP \[bu]
1204: The generation was wrong (and generation was specified)
.IP \[bu]
-32602: invalid parameters

.RE
.SH AUTHOR

Rusty Russell \fI<rusty@rustcorp.com.au\fR> is mainly responsible\.

.SH SEE ALSO

\fBlightning-listdatastore\fR(7), \fBlightning-deldatastore\fR(7)

.SH RESOURCES

Main web site: \fIhttps://github.com/ElementsProject/lightning\fR

\" SHA256STAMP:0ef09e6f98d7e34e7d8339351c29ffc70be71fbf9f05f581488e3c7f603d3721