Skip to content

Database governance built for humans and agents — controlling changes and access across every major database.

docs: fence star upserts against project purge too (codex review)

Dannyee19ecbf26c6
diff --git a/docs/design/saved-queries-model.md b/docs/design/saved-queries-model.md
index 5204dd98a3..333beb50e6 100644
--- a/docs/design/saved-queries-model.md
+++ b/docs/design/saved-queries-model.md
@@ -553,16 +553,26 @@ lock-ordering):
row and reject the write unless the project is active — a create racing a
purge fails cleanly (`FAILED_PRECONDITION`), never as an FK violation and
never leaving a row in a project mid-deletion.
+- **Star upserts require an *existing* saved query.**
+ `UpdateSavedQueryStar` inserts a `saved_query_star` child, so it locks the
+ target `saved_query` row before the upsert and proceeds only if it still
+ exists — a star racing the query's purge either no-ops as `NotFound` (the
+ row is already gone) or is removed by the cascade, never a raw FK failure.
+ (`BatchUpdateSavedQueries` only *updates* existing `saved_query` rows, so
+ its row locks give the same guarantee with no new child; folder moves
+ affecting a purged row simply touch zero rows.)
- **Purge deletes saved queries explicitly.** `BatchDeleteProjects`'
hard-delete path lists `saved_query` (as it lists `worksheet` today);
`saved_query_star` then cascades from it.
-Both paths take the project lock in the same order, so create and purge
-serialize rather than deadlock. Required before implementation: deterministic
-real-PostgreSQL regression tests for **both** acquisition orders
-(create-then-purge, purge-then-create), asserting the terminal outcomes —
-project deleted, no orphaned saved query, and **no** FK failure in either
-direction (absence of SQLSTATE `40P01` alone is insufficient).
+Every writer locks its FK parent before inserting (create → the `project`
+row; star → the `saved_query` row) in that fixed order, so writers and
+purge serialize rather than deadlock. Required before implementation:
+deterministic real-PostgreSQL regression tests for **both** acquisition
+orders of each writer against purge (create↔purge and star↔purge),
+asserting the terminal outcomes — project deleted, no orphaned saved query
+or star, and **no** FK failure in either direction (absence of SQLSTATE
+`40P01` alone is insufficient).
### Sharing and organization UX