> Agent-readable docs index: /llms.txt. Download /docs.zip to grep all markdown files locally.

---
title: db
description: Persistent key-value storage across sessions
icon: database
---

The `db` namespace is a persistent key-value store that survives across sessions. Index `db` with any key name to read its value, or assign to it to write.

## Utilizing database

```lua
db.key_name: any
```

```lua
db.key_name = value
```

> Reads or writes a persistent value by key.

<Schema title="Parameters">
  <SchemaField name="key_name" type="any" required>
    Name of the key.
  </SchemaField>

  <SchemaField name="value" type="any">
    Value the key should be set to. This can be anything that can be sanitized (no functions, userdata).
  </SchemaField>
</Schema>

<Warning>
  Indexing database keys is a heavy process. Do not do it inside callbacks that are called many times per second.
</Warning>

<Expandable title="Example">
  ```lua lines=false
  -- look up for database key named "test"
  -- returns the new table if database returned nil
  local data = db.test or { }

  data.name = 'Salvatore'
  data.project = 'Spirthack Innovations LLC'

  events.shutdown:set(function()
      -- replace "test" key with the new value
      db.test = data
  end)
  ```
</Expandable>
