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

# Backup & Restore

> Consistent snapshots, checksum-verified restore, and portable JSON export/import for the iCommerce engine.

# Backup & Restore

The recovery layer, exposed through the embedded accessor, the Node binding, and five MCP
tools — so an agent can back up and restore the engine it carries.

## Backup

```js theme={null}
maintenance().backup_to(path)
```

Takes a consistent snapshot via SQLite `VACUUM INTO`, which is **safe under concurrent
writers**. Alongside the snapshot it writes a sidecar manifest recording:

* Schema version
* Migration count
* Engine version
* Size
* A SHA-256 checksum, verified after writing

## Restore

```js theme={null}
maintenance().restore_from(path)
```

Restore is deliberately conservative. It:

* **Verifies the checksum** from the manifest.
* **Refuses backups newer than the running binary** — you cannot restore a future schema into an
  older engine.
* **Refuses to overwrite a non-empty target** without an explicit flag.
* **Refuses to replace the database the instance currently has open.**
* **Swaps atomically** — temp file, fsync, rename.

## Portable export and import

```js theme={null}
maintenance().export_all()
maintenance().import_all(envelope)
```

Streams a **versioned JSON envelope** across core commerce and finance domains. The round trip
is proven by an export → import → re-export acceptance test.

<Warning>
  **Import is content-preserving, not identity-preserving.** Repository `create` methods mint new
  IDs, so foreign keys are remapped in dependency order. For identity-preserving disaster
  recovery use a **backup/restore**, not export/import.
</Warning>

### Export coverage

Export covers core commerce and finance domains. **Returns, invoices, payments, and bills are
export-only** — their state-machine history cannot be replayed through a single `create`.
Coverage is documented in the module docs.

## Choosing between them

| Goal                                               | Use                          |
| -------------------------------------------------- | ---------------------------- |
| Disaster recovery, identical restore               | `backup_to` / `restore_from` |
| Moving data between engines or environments        | `export_all` / `import_all`  |
| Inspecting or transforming data outside the engine | `export_all`                 |

## Related

* [API Hardening](/stateset-icommerce/stateset-icommerce-api-hardening)
* [Embedded engine](/stateset-icommerce/stateset-icommerce-embedded)