Documentation
12. Persistence
Save and reload a full RelPyDB object while preserving relational structure.
Persistence mental model
save() stores the full RelPyDB object state needed to reconstruct the database later: schema, data, auto sequences, internal row ids and index definitions. It does not store views and it does not store encryption keys.
Functions
| Function | Signature | Meaning |
|---|---|---|
save | save(file_path, *, indent=2) -> None | Writes a RelPyDB JSON persistence file. |
load | RelPy.load(file_path, *, encryption_key=None) -> RelPy | Loads a RelPyDB file and rebuilds indexes. |
Example
Save
db.save("shop.relpy.json")Load
loaded = RelPy.load("shop.relpy.json")For encrypted databases:
loaded = RelPy.load("shop.relpy.json", encryption_key=key)Persistence vs export
| Feature | save() | to_json() |
|---|---|---|
| Purpose | Restore RelPyDB object | Public data export |
| Includes schema | Yes | No |
| Includes internal row ids | Yes | No |
| Encrypted values | Ciphertext | [ENCRYPTED] unless decrypt=True |
| Rebuild indexes on load | Yes | Not relevant |
Benchmark: build and persistence timing
From a benchmark run with 200 customers, 200 orders, 250 support tickets (10 tables total):
| Operation | Time |
|---|---|
| RelPyDB build (schema + inserts) | 8.95 ms |
| SQLAlchemy/SQLite build | 13.04 ms |
| DuckDB build | 206.47 ms |
RelPyDB save() | 7.67 ms |
RelPyDB load() | 6.11 ms |
| Persistence file size | 385 KB |
RelPyDB's round-trip time (save + load) is under 14 ms for a mid-sized dataset.