Changes and changesets
How writes are recorded, grouped, approved and rolled back.
Change
A change is one recorded modification to one row, or to the schema, with the before and after values of what it touched. Changes are appended to the workspace’s change log and never edited.
Changeset
A changeset is a group of changes by one actor that is reviewed and rolled back as a unit. It is always either entirely applied or entirely pending.
How writes are grouped:
- By default, an agent’s consecutive writes group into one changeset per stretch of work, usually one per request.
begin_changesetstarts a new, named group. The label shows on Changes and is searchable.- A batch (
write_batch, orapp.batchfor apps) is one call carrying up to 100 inserts, updates and deletes that become exactly one changeset under its label. - A write that waits always gets a changeset of its own.
For an app, a label begun with POST /v1/changesets {"label"} stays on its changesets until a new label or ten idle minutes. Use a batch when writes must stay together.
Batch
A batch is all or nothing:
- If every write in it may apply, they all apply.
- If any write would wait, the whole batch waits, and nothing applies until the owner approves.
- One invalid write refuses the whole batch, naming it (
writes[2]: …). - Every write picks its rows as the batch arrives, not after the batch’s earlier writes. A later write in the batch doesn’t see rows an earlier one inserted.
Pending changeset
A pending changeset has been requested but not applied, because the actor’s approval rules say that kind of write waits.
- Its targets are fixed when it is requested. When approved, it acts on the rows its filter matched then. Matching rows added meanwhile are left; the approval screen says how many and who added them.
- If rows it targets changed since, approving shows the difference and asks again.
- While an insert waits, its rows don’t exist. An agent’s
querysays how many rows are waiting instead. - The actor can withdraw its own pending changeset. A pending changeset left past the history window expires: nothing of it was applied, and it is purged.
Statuses: pending, applied, rejected, withdrawn, expired.
Approval
Approval is the owner’s decision to apply a pending changeset. It happens only on Tabulic’s screens. In hosts that support MCP Apps, a pending write shows its diff inline in the chat with a link to approve it there; the approval itself never happens in the conversation.
Rollback
A rollback undoes an applied changeset by applying the reverse of each of its changes. It is itself a new changeset by the owner, so it can be rolled back too. Each changeset is rolled back at most once; to bring its changes back, roll back the rollback.
Conflicts
A conflict is a cell that a rollback would revert, but that the owner or an app has changed since. The owner chooses, per cell, whether to keep the later value or revert. Keeping any cell of a row keeps that row.
Cascade
A cascade is the later changes by agents that a rollback also reverses because they depend on what it removes, such as writes to a table whose creation is being rolled back. Later changes by the owner and by apps never cascade; they become conflicts instead.
Rows added since
If rows were added since to a table a rollback brings rows back into, nothing removes them. The rows brought back sit beside them, and the rollback screen says how many were added and by whom.
Drop
A drop removes a table or column from view. Its data is kept until the history window passes, so rolling back the drop restores it, along with agents’ access to it.