> For the complete documentation index, see [llms.txt](https://docs.marioded.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marioded.com/configure-and-customize/storage.md).

# Storage and backups

Choose where recordings live, connect SQL storage, and back up the complete replay archive.

Use local storage to get started. Use shared SQL storage when recordings need to be available on several machines.

## Choose a backend

| Backend                                  | Good fit                                | Important property                                                        |
| ---------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------- |
| `SPATIAL`                                | One-machine use and local development   | Replay files and content-addressed terrain live on disk.                  |
| `DATABASE` with MariaDB/MySQL/PostgreSQL | Multiple gameplay/lobby/replay machines | Metadata, event payloads, and captured terrain can be shared through SQL. |
| `DATABASE` with SQLite                   | A local SQL-backed installation         | A local database file is not a multi-machine service.                     |

Your storage choice applies when the server starts and is used for both recordings and captured terrain.

{% hint style="info" %}
**Redis is not replay storage.** It can coordinate lobby transfers, but events, metadata, and captured terrain still need local or SQL storage.
{% endhint %}

<details>

<summary>What does Reverse store on disk?</summary>

With local storage, recordings are kept in `plugins/recordings`:

```
plugins/
  reverse-recorder/
  reverse-player/
  reverse-lobby/
  recordings/
    <replay-uuid>.rpl
    .replay.lock
    manifests/
    chunks/
      index.dat
      packs/
        pack-000000.dat
        ...
```

Some terrain-index paths use encoded subdirectories rather than a simple visible template name. Treat the entire storage tree as one managed dataset.

The `.rpl` files hold recorded actions, while the other recording folders hold the terrain they need. Keep the whole `recordings` folder together. Do not remove individual terrain files because they appear to belong to an old replay; several recordings may share them.

For several machines, use shared SQL storage rather than treating a network-mounted folder as a database.

</details>

## SQL configuration

Set `storage.type: DATABASE` and configure the nested database section. Port defaults in the generated file are MySQL-oriented, so use 5432 explicitly for PostgreSQL.

The configured account needs permission to create Reverse's tables and read/write its data. Back up before changing storage or updating the plugin, and avoid editing recording data directly in database tables.

SQLite normally stores its file under `plugins/recordings`. For a remote database, connection limits are configured under `storage.database.pool`.

## Fallback behavior

`fallback-to-spatial: true` allows a failed SQL startup to select local storage instead. The log reports:

```
Database unavailable; using spatial storage: ...
```

This is not replication, automatic re-upload, or a live switch back to SQL. Repair the database and restart deliberately. Recordings created locally during fallback remain local unless you perform a separately planned transfer.

For shared deployments, `false` is usually easier to operate: a node fails clearly instead of serving a different private catalog.

## Catalog versus full replay loading

Browsing the catalog does not load every recording for playback. Renaming a replay or editing its description changes its catalog text, not the recorded scene. Reopen the catalog to see updated details.

## Cache sizing

The shared configuration exposes maximum chunks, terrain indices (historically named manifests), and loaded replays. They are count limits, not megabytes. A loaded replay can be much larger than its compressed `.rpl` file.

Leave cache limits at their defaults unless you have a reason to tune them. Watch server memory use when increasing them. Cache limits do not delete saved recordings.

## Back up correctly

{% hint style="warning" %}
**Back up events and terrain together.** Copying only `.rpl` files can leave a recording without the world it needs to display.
{% endhint %}

### Local storage

1. Stop new recordings.
2. Wait for pending saves, then stop the affected servers cleanly.
3. Copy the **entire** `plugins/recordings` tree, including replay files, indices, and packs.
4. Back up any SWM templates and their configured loader data separately.
5. Restore a test copy and replay a known recording before relying on the backup.

### SQL storage

Use the database engine's consistent backup method for the entire Reverse dataset. Include all replay metadata/event tables and terrain data/index tables from the same consistent snapshot. Back up external SWM templates separately.

### Redis

Availability data is short-lived coordination state, not the replay archive. A Redis snapshot alone cannot restore recordings. Stale heartbeats and expired pending selections are normal control-plane concerns, not lost replay payloads.

## Deletion and migration

Use the catalog's authorized delete operation or a configured menu delete action for replay deletion. Do not assume deletion compacts terrain packs or provides a configurable retention schedule. No owner-facing automatic retention/garbage-collection command is documented by the current command surface.

Changing `SPATIAL` to `DATABASE` does not import existing files. There is no current general-purpose migration command. Keep the original backup and plan migration using supported storage APIs/tools for the exact build.

## Related guides

* [Exact storage configuration keys](/configure-and-customize/configuration.md).
* [Connect the same archive to lobby and player](/use-reverse/network.md).
* [Understand captured terrain and templates](/configure-and-customize/terrain.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.marioded.com/configure-and-customize/storage.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.