LIGHTNING-DATASTORE(7)

💾 datastore — Command for storing (plugin) data ✨

Okay bestie, welcome to LIGHTNING-DATASTORE(7) — the glow-up guide to the datastore command, your plug-in's own little locker inside the Core Lightning database 💅

---

🌸 SYNOPSIS 🌸

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

That's the whole vibe. Now let's get into it 🫶

---

✨ DESCRIPTION ✨

The datastore RPC command lets plugins stash data in the Core Lightning database so they can come back for it later. It's literally a little storage unit for your plug-in, and it's the moment 🎀

• key (one of) — okay so this is important: a key can have children or a value, never both 🚫. Parents get created and removed automatically, so you never have to manage them yourself. The key can be:
  • (array of strings) — an array of values that forms a hierarchy (though a single value is treated as a one-element array, cute). Using the first element of the key as the plugin name (e.g. [ 'summary' ]) is recommended 💡
  • (string, optional)
  • (string)
• string (string, optional) — the data to be saved, in string format 📝
• hex (hex, optional) — the data to be saved, in hex format 🔢
• mode (string, optional) (one of "must-create", "must-replace", "create-or-replace", "must-append", "create-or-append") — the write mode, i.e. how the record gets updated:
  • must-create: fails if it already exists 😤
  • must-replace: fails if it doesn't already exist
  • create-or-replace: never fails, main character energy, unbothered 👑
  • must-append: must already exist, and it appends this to what's already there
  • create-or-append: appends if anything is there, otherwise creates it
  • The default is must-create ⭐
• generation (u64, optional) — if you specify it, the update fails when the previously-existing data isn't exactly that generation. That's how you get simple atomicity, no cap. This is only legal with mode must-replace or must-append ⚠️

---

💖 RETURN VALUE 💖

On success you get an object back, and it contains:

• 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 💀

These are the error codes that may occur, bestie, don't panic:

• 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. Iconic, honestly 🫶

---

🦋 SEE ALSO 🦋

lightning-listdatastore(7), lightning-deldatastore(7), lightning-datastoreusage(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.9 — that's the version, and the page is dated LIGHTNING-DATASTORE(7), so there you go bestie, go store some data, slay 💜✨