Approval rules
Which writes apply at once and which wait for the owner, per agent and per app.
An approval rule is a per-actor setting, for one kind of write, of whether it applies at once or waits as a pending changeset. Each agent and app has its own set in each workspace, plus a bulk threshold.
Kinds of write
| Kind | What it covers | Agent default | App default |
|---|---|---|---|
insert | adding rows, up to the threshold | applies | applies |
update | changing rows, up to the threshold | applies | applies |
delete | deleting rows, up to the threshold | waits | applies |
bulk-insert | adding more rows than the threshold in one write | applies | applies |
bulk-update | changing more rows than the threshold in one write | waits | applies |
bulk-delete | deleting more rows than the threshold in one write | waits | applies |
create | a table or column | applies (always, for now) | n/a |
rename | a table or column | applies (always, for now) | n/a |
drop | a table or column | waits | n/a |
change-type | a column’s type | waits | n/a |
The bulk threshold is 10 rows unless the owner changes it. It counts rows touched by one write; fifty single-row writes are fifty small ones.
Apps never change the schema, so only the row kinds apply to them. Their writes apply by default because a person clicking in an app can’t wait for an approval.
How rules are checked
- A rule is checked when the write is made. Changing a rule never touches writes already waiting or applied.
- In a batch, if any write would wait, the whole batch waits.
- A write that waits says which rule held it back (
waits_for,reason) and links to where the owner reviews it (review_url). - The owner’s own writes never wait.
Who sets them
Only the owner, on the Agents screen (or an app’s Settings). An agent can read its own rules with describe_schema but never change them.
There is no floor: any kind may be set to apply at once, since every change can still be rolled back within the history window. On the hosted service, rules looser than the defaults need the paid plan; on the free plan a looser rule acts as the default.
For agents
When a write comes back with "status": "pending":
- Tell the person it is waiting for their approval, with the link if there is one.
- Don’t retry it. Retrying creates another pending changeset.
- Check later with
changeset_status, or take it back withwithdraw_pending.