> For the complete documentation index, see [llms.txt](https://atiysus-organization.gitbook.io/aty-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://atiysus-organization.gitbook.io/aty-scripts/inventory/getting-started/database.md).

# Database

## Database

Seven tables. **You do not create them** — the resource applies its own schema at boot, idempotently, every start. There is no migration step to forget.

{% hint style="info" %}
`sql/schema.sql` ships for DBAs who want to review or pre-create the two core tables by hand. Running it is optional; skipping it changes nothing.
{% endhint %}

#### The two that hold the product

| Table             | Holds                                              |
| ----------------- | -------------------------------------------------- |
| `aty_inventories` | Every container and what is in it                  |
| `aty_ledger`      | The movement history the auditor and rollback read |

#### The four the admin panel writes

These exist because the panel edits things **without touching your config files**. The file stays the developer's copy; these tables are the layer on top, and the panel shows both so nobody has to guess which one is running.

| Table           | Holds                                             |
| --------------- | ------------------------------------------------- |
| `aty_overrides` | Item fields and shop prices edited from the panel |
| `aty_settings`  | Settings changed from the panel                   |
| `aty_places`    | Shops and stashes created from the panel          |
| `aty_recipes`   | Drag-craft recipes created from the panel         |

#### And one for the world

| Table        | Holds                                                 |
| ------------ | ----------------------------------------------------- |
| `aty_placed` | Props set down in the world, so they survive restarts |

#### `aty_inventories`

| Column                     | Purpose                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------- |
| `id`                       | Container identity — `player:ABC12345`, `stash:policelocker:ABC12345`, `trunk:XYZ789` |
| `type`                     | `player`, `stash`, `evidence`, `trunk`, `glovebox`, `wear`, `container`, `placed`     |
| `owner`                    | Citizen id where the container belongs to somebody; the plate for a boot or glovebox  |
| `max_weight` / `max_slots` | The container's size, in grams and slots                                              |
| `data`                     | The slots, as JSON                                                                    |
| `version`                  | Increments on every commit — this is how two writers are kept apart                   |
| `updated_at`               | Last commit                                                                           |

The `version` column is the concurrency guard. A move carries the version the player's panel was drawn from; if the container has changed since, the move is refused and the panel is handed fresh state rather than acting on a stale screen.

Ground piles are never written here. They live in memory only and are gone after a restart.

#### `aty_ledger`

One row per movement. This table only ever grows.

| Column                | Purpose                                                                        |
| --------------------- | ------------------------------------------------------------------------------ |
| `tx_id`               | Transaction id — several rows share one, and a rollback reverses them together |
| `item`                | Item name                                                                      |
| `count`               | Signed: `+6` in, `-2` out                                                      |
| `from_inv` / `to_inv` | Container ids. An empty `from_inv` means created, an empty `to_inv` destroyed  |
| `actor`               | Who caused it — a citizen id, `console`, `airdrop`, `system`                   |
| `reason`              | `buy`, `use`, `craft`, `move`, `give`, `drop`, `evidence_out`, …               |
| `meta`                | Serial numbers and anything else worth keeping                                 |
| `at`                  | Timestamp                                                                      |

#### Growth and retention

A busy server writes a few thousand ledger rows a day. The table is indexed on `tx_id`, and on `item` and `actor` each together with `at`, so it stays fast well past a million rows.

There is deliberately **no automatic pruning** of the ledger. An audit trail that quietly deletes its own history is not an audit trail. If you trim it, know what you are giving up: rolled-back transactions and serial traces only reach as far back as the rows you keep.

{% hint style="warning" %}
`aty_inventories` is pruned. `Config.ClearStashes = '6 MONTH'` (ox\_inventory's `inventory:clearstashes`) deletes, at resource start, every `stash` and `evidence` row whose contents have not changed in that long — personal lockers, job stashes and evidence lockers included. Bags, worn kit, boots, gloveboxes, bags inside bags and placed objects are never touched. The first start after the setting appears only prints what it would delete; deleting begins from the start after that. `false` keeps everything.
{% endhint %}

#### Backups

Back up `aty_inventories` and `aty_ledger` together. The first without the second restores the items but loses the ability to explain them; the second alone explains items that no longer exist.

Include the four panel tables too, or a restore silently reverts every item edit, setting, shop and recipe your admins made from the panel.

{% hint style="danger" %}
Never restore `aty_inventories` from an older snapshot while the server is running. Loaded containers are held in memory and written back whole on their next commit and when the resource stops, so every container that was loaded quietly overwrites the row you restored. Stop the resource first.
{% endhint %}