> ## Documentation Index
> Fetch the complete documentation index at: https://mikting.docs.komo.moe/llms.txt
> Use this file to discover all available pages before exploring further.

# Key-value store

> Scopes, expiration, and persistent data.

Use the store for data that scripts need between runs, such as counters,
inventories, or moderation strikes. Values are JSON and can have an
expiration time, or TTL. The default size limit is 64 KiB per value,
configured by `maxValueBytes`.

`MiktingStore` uses Node.js's built-in `node:sqlite`. It also supports an
in-memory backend. The SQLite table is
`kv(key, scope_type, scope_id, value_json, expires_at, updated_at)`.

## Scopes

A scope separates values with the same key. The scope ID comes from the
current event context.

| Scope | Scope ID |
| - | - |
| `global` | `global` |
| `guild` | Guild ID. |
| `user` | User ID. |
| `channel` | Channel ID. |
| `message` | Message ID. |

For example, `coins` in the `user` scope has a separate value for each user.
If the context lacks the requested scope ID, the store falls back to the
shared `global` scope. Supply a member context when storing per-user data.

## Set, read, and update values

```yaml theme={null}
- id: miktingStoreSet
  args: { key: coins, value: 100, scope: user, ttlSec: 3600 }
- id: miktingStoreGet
  args: { key: coins, scope: user, storeAs: coins }
- id: miktingStoreIncr
  args: { key: messages, by: 1, scope: user, storeAs: total }
- id: miktingStoreListOp
  args: { op: append, key: inventory, value: sword, scope: user }
- id: miktingStoreListOp
  args: { op: list, key: 'shop.', scope: global, storeAs: keys }
- id: miktingStoreRemove
  args: { key: coins, scope: user }
# key: '*' clears the whole scope
```

A missing key sets `[[mikting_error]]` to `missing_key:<k>`.
`miktingStoreIncr` updates values atomically on both backends and preserves
an existing TTL. Incrementing a nonnumeric value fails with
`not_a_number:<k>`.

The `list` operation matches key prefixes literally, including `%` and `_`,
and returns keys from the selected scope only. Setting `key: '*'` on
`miktingStoreRemove` clears that scope.

## Storage configuration

```yaml theme={null}
storage: { driver: sqlite, path: configs/Mikting/store.db,
  defaultTtlSec: 0, maxValueBytes: 65536 }
```

`driver: memory` stores data in memory without writing to disk. If SQLite
cannot open the database file, the addon logs a warning and uses the memory
fallback. `/mikting-status` then shows `memory(fallback)`.

For persistence on Pterodactyl, place `store.db` on a persistent volume.
Data in memory is lost when the bot restarts.

## Converting meta actions

For new scripts, use the store actions. The following table maps common
`meta*` operations to their store equivalents.

| Meta action | Store action |
| - | - |
| `metaSet {key,value}` | `miktingStoreSet {key,value,scope: user}` |
| `metaAdd/metaSubtract` | `miktingStoreIncr {by: N/-N}` |
| `metaListAdd` | `miktingStoreListOp {op: append}` |
| `metaRemove` | `miktingStoreRemove` |
| `metaToggle` | `miktingStoreGet`, followed by `miktingBranch` and `miktingStoreSet`. |

Inspect stored data with `/mikting-store get|list`. The command truncates
values and redacts secrets.

[Documentation home](https://mikting.docs.komo.moe/index.md) · [Source Markdown](https://gitlab.com/komomori/mikting/-/blob/main/docs/mikting-store.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.