Recover Data from Version History

Open inAnthropic

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

Example: Bash
export AUTH="admin:root"
export SERVER="http://localhost:6363"
export DB="admin/MyDatabase"
Interactive demo
Open walkthrough

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:

Example: Bash
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"}'
Run the example above first to populate this value.

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:

Example: Bash
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"}'
Run the example above first to populate this value.

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, and timestamp on 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

Was this helpful?