What you will take away from this lesson
Every system that changes will one day change for the worse. What separates a platform from a pile of scripts is what happens in the next five minutes. On Plexara an administrator presses Roll back, the application is running its previous release, and the record shows who did it and why. Then the agent finds the fault at its own pace, with no customer waiting on it.
This lesson rolls the shop back from its second release, follows what happens to its schema, and then reads the diagram: the picture of the application that is drawn from the parts themselves and so cannot be out of date.
Learning Objectives
- 01Roll an application back to an earlier release and read what the rollback records.
- 02Say what a rollback does to automations, assets, a site environment and migrations.
- 03State the rule that decides whether migrations are reverted, and why it is all or none.
- 04Read an application’s diagram: what its nodes and links are and where they come from.
- 05Name the three findings the diagram reports and which one refuses a release.
Where this lesson sits
Lesson 904 released the shop and left a change waiting. That change, gift wrapping, became release 2. This lesson begins a day later, with a report that its totals are wrong.
900 Series: Applications
- 901What an application isOne record for a whole system: its parts, who owns it, who releases it, and the order an agent builds it in.
- 902A database of its ownA transactional schema the application owns, built from reviewed migrations, with its own role and row-level security keyed on the caller.
- 903The work: automations, forms and endpointsA checkout in one transaction, an API the database filters, a confirmation per order, scheduled upkeep, and tests on a real copy of the database.
- 904Releases: what runs is what was releasedWhat a release applies, pins, records and refuses, who may make one, and what a save does after it.
- 905Rollback and the diagramRestoring an earlier release in one step, what happens to migrations, and a diagram drawn from the parts with findings and comparisons.
- 906Pages people openA browser address of the application’s own: page endpoints, pinned static files, viewer sign-in, public storefronts, and a site environment as a part.
- 907Capstone: the shop, end to endThe shop assembled from one request, released, changed, released again and rolled back.
The 900 series assembles what the 600 series and the 700 series taught one part at a time: automations, endpoints and forms become one application with a database of its own, released as a whole.
Rolling back
The administrator does not need to know what is wrong to act. They need the shop to be correct again.
Rolling the shop back
What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.
→ manage_application
{
"command": "rollback",
"application": "shop",
"note": "Gift-wrap totals were wrong on multi-line orders."
}
← {
"number": 3,
"action": "rollback",
"restored": 1,
"migration_version": 5,
"changes": {
"parts": [
{ "kind": "script", "part_id": "shop-checkout", "from": 4, "to": 3 },
{ "kind": "asset", "part_id": "storefront", "from": 5, "to": 4 }
],
"applied": [],
"reverted": [6]
},
"created_by": "[email protected]"
}Release 2 added gift wrapping: a new column on order lines (migration 6), version 4 of the checkout and version 5 of the storefront. Its totals were wrong. The rollback names no target, so it restores the release before the current one.
The answer is release 3. A rollback does not erase release 2; it records itself as a new release that restored release 1’s pins and reverted migration 6. The checkout is back at version 3 for every customer, and version 4 is still saved, ready to be fixed.
What a rollback does
A rollback is a release whose content is an earlier release.
What a rollback does
- 1
Every pin is restored together
Automations, assets and a site environment that is a part all return to the versions the earlier release pinned. The API, the checkout, the storefront and the site move back as one.
- 2
It is a release, and it is recorded
The rollback gets the next release number, the administrator’s name, their note, and the list of what moved. The history never has a gap.
- 3
Any earlier release can be the target
With no target the rollback restores the release before the current one. An administrator can name any earlier release instead.
- 4
Nothing saved is lost
The newer versions of the automations and assets still exist. They are simply not pinned. The next release can pin them again once they are right.
A rollback takes effect at once: the next request, the next event and the next scheduled run execute the restored versions.
The schema on the way back
Code can always be put back. Whether the schema goes back with it depends on how its migrations were written.
What happens to the schema
Every migration since has a down
- The rollback reverts each migration applied since the target release with the down SQL the agent wrote beside it. The schema returns to what the restored code expects.
One of them has no down
- The rollback reverts none of them and says which one stopped it. The pins are still restored. Reverting some and not others would leave a schema no release ever described, so the rule is all or none.
Migrations from before the application
- A schema that already had migrations applied when it joined the application keeps them. A rollback never reverts a migration that no release applied.
This is why the agent writes a down for every migration and why the review in lesson 902 holds the down SQL to the same rules as the up. A migration written to be additive, a new nullable column or a new table, keeps old code working either way, and the agent prefers that form for exactly this reason.
The diagram
To find what release 2 changed, the agent and the administrator look at the same thing: the application’s diagram.
What the diagram draws
Nodes
- The application’s parts, and what they reach outside it: the tables of its schema, tables on other stores, notification channels, shared libraries, outputs and endpoints. A schedule or an endpoint binding is shown on its automation’s card.
Links
- A webhook source starting an automation. An automation reading or writing a table, loading a library at a version, exporting or refreshing an asset, notifying a channel, or submitting a form to its source. An asset calling an endpoint or embedding a form.
Where they come from
- The diagram is read from the parts’ sources and stored settings: the SQL an automation contains, the bindings it holds, the content of an asset. It is never drawn from a run. Opening it starts no run and makes no request to anything outside.
Names decided at run time
- A name an automation computes when it runs, such as an output named by the date, is drawn as a node marked computed. The diagram shows that it exists and does not guess what it will be called.
The diagram can be drawn for the current release, for the newest saved versions, or for any past release. The same picture answers what is running, what is about to run and what was running last month.

Comparing releases
The diagram can show one version of the application against another.
Comparing two releases
- 1
Pick two versions of the application
Turn on Show changes since and choose a release. The diagram marks every node and link as added, removed or unchanged between the two.
- 2
A part whose version moved is marked changed
The checkout at version 4 against version 3 is one changed card, with the links it gained or lost drawn beside it.
- 3
What the change reaches is visible
A release that makes an automation notify a new channel, write a new table or load a newer library shows that as a new link. Reach is the thing a reviewer most needs to see and the thing a list of version numbers hides.
Before releasing, an administrator compares the newest versions with the current release and reads the difference as a picture: this release makes the checkout write one more table and nothing else.
What the diagram finds
Because the diagram is read from the parts, it can notice what does not add up.
Findings
A library at the wrong version
refuses a release
- An automation loads one of the application’s own libraries at a version other than the one the release would pin. Inside an application the release’s pin is the version, so the release is refused until the automation loads it.
A table read and never written
recorded
- A table of the application’s schema that its automations read and no part writes. A table its migrations fill counts as written. It usually means a part is missing from the application.
A schema the application does not hold
recorded
- An automation uses a schema that is not the application’s. The database will refuse it at run time; the diagram says so first.
Findings appear above the diagram, in the answer to manage_application get, and on each release. A save to an automation that belongs to an application returns the findings that save introduced, so the agent learns about a problem in the same call that created it and corrects it before anyone else looks.
A picture computed from the system
Pages
Key terms
Four terms cover the way back and the picture of the system.
Key Terms
- Rollback
- A release that restores the pins of an earlier release. It reverts the migrations applied since when every one of them has a down migration, and none of them otherwise.
- Down migration
- The SQL that reverts a migration, written with it and held to the same review.
- Diagram
- A drawing of how an application’s parts fit together, read from their sources and settings for any release, with an optional comparison against another.
- Finding
- A problem the diagram reads from the parts: a library at the wrong version, a table read and never written, or a schema the application does not hold.
