Every write in TerminusDB creates an immutable commit. Data is never lost — only the branch HEAD moves forward. This tutorial shows how to use the commit log to identify a known-good state and reset your branch to recover from a bad change.
Time: ~10 minutes Prerequisites: TerminusDB running on localhost:6363 (Install guide →)
Setup
export AUTH="admin:root"
export SERVER="http://localhost:6363"
export DB="admin/MyDatabase"Step 1 — Create a database with initial data
Create the database:
Loading…Insert an initial document:
Loading…Step 2 — Make a second commit (the "good" state)
Update the product price — this creates a second commit that we will later identify as "last known good":
Loading…Step 3 — Make a bad change (simulate data corruption)
Delete the product entirely — this is the change we want to recover from:
Loading…Verify it is gone:
Loading…You should get a document-not-found error — the document no longer exists on main.
Step 4 — View the commit log
Use the /api/log/{path} endpoint to list recent commits:
Loading…The response includes additional internal fields: @id (commit IRI), instance and schema (storage layer references), and parent (link to previous commit, absent on the initial commit). For recovery purposes, focus on identifier, message, and timestamp.
Identify the commit you want to return to. In this case it is the second commit ("Update widget price to 12.50") — the last one before "Accidentally deleted product".
Reading timestamps
Timestamps are Unix epoch seconds. Convert to human-readable with: date -d @1714399900 (Linux) or date -r 1714399900 (macOS).
Step 5 — Create a branch from the good commit (verify before reset)
Before resetting main, create a branch from the good commit to inspect the data safely. First fetch the identifier of the commit just before the bad one — start=1 skips the newest (the delete) entry:
curl -s -u admin:root \
"http://localhost:6363/api/log/admin/MyDatabase?count=1&start=1"Then create the branch from that commit — the identifier flows in automatically:
curl -s -u admin:root -X POST \
"http://localhost:6363/api/branch/admin/MyDatabase/local/branch/recovery-check" \
-H "Content-Type: application/json" \
-d '{"origin": "admin/MyDatabase/local/commit/GOOD_COMMIT"}'Step 6 — Verify the data on the recovery branch
Query the recovery branch to confirm it contains the expected data:
Loading…The document is present with "price": 12.50 — the state before the accidental delete.
Step 7 — Reset main to the good commit
Now that we have confirmed the data is correct, reset main to the same good commit:
curl -s -u admin:root -X POST \
"http://localhost:6363/api/reset/admin/MyDatabase" \
-H "Content-Type: application/json" \
-d '{"commit_descriptor": "admin/MyDatabase/local/commit/GOOD_COMMIT"}'Reset moves the branch HEAD back to the chosen commit — it does not delete the bad commit, history stays intact.
Step 8 — Confirm the recovery
Verify that main now has the document restored:
Loading…The document is present with "price": 12.50 and "status": "active" — recovery complete.
Cleanup
Loading…What you learned
- Every write creates an immutable commit — data is never lost, only HEAD moves forward
- The commit log is the audit trail —
author,message, andtimestampon every commit - Reset moves the branch HEAD backward — it does not delete commits from history
- Branch from a commit to inspect safely — verify before resetting production data
Next steps
- How to Set Commit Messages — make the log useful for recovery
- Audit Data Changes — use the commit log for compliance auditing
- Diff and Patch Operations — compare specific commits