utopia-php / utopia-php/database
createCollection: make the metadata row the atomic claim so concurrent creators cannot drop each other's schema
Nobody has claimed this yet.
- Dominant language
- PHP
- Stars
- 74
- Forks
- 59
- Avg merge
- 10h 45m
- Merged PRs (30d)
- 20
Description
Follow-up to #938, which fixed the two reachable orderings but deliberately left this one open.
The residual window
createCollection() creates the physical table first and inserts the metadata row second, so between those two steps a collection exists that nothing in metadata describes. A second creator that reads metadata inside that window sees nothing, takes the adapter's Duplicate as proof of an orphan, and drops the first creator's table. The first creator's metadata insert then commits, pointing at a collection that is no longer there.
#938 re-reads metadata past the cache before concluding a table is an orphan, which removes the orderings that a rolling restart actually hit, and stops the loser from rolling back a table the winner owns. It does not make the sequence atomic — nothing serialises the two creators.
Proposed fix
Insert the metadata row first, then create the physical table. The unique key on _uid becomes the claim: exactly one creator wins it, and the loser gets Duplicate before it can touch any schema. On a physical-create failure the winner rolls back its own metadata row.
This is a design change, not a patch:
- it inverts the ordering of a hot path
- the transient orphan state becomes "metadata without a table" instead of "table without metadata", so orphan recovery has to be rewritten around the new shape
- every existing rollback path changes what it is rolling back
Testing
Needs a seam the code does not currently have: a way to pause one creator after its schema write and before its metadata write, so a second creator can be driven through the window deterministically. #938's testCreateCollectionConcurrentlyKeepsPeerData covers the cache-driven orderings but cannot reach this one.
The absence of that seam is itself part of the work.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start at createCollection() and read the existing rollback and orphan-recovery paths, using testCreateCollectionConcurrentlyKeepsPeerData as the current concurrency test. Add a seam that pauses a creator between schema and metadata operations, then cover the metadata-first claim and competing creators deterministically. Done means the loser cannot drop the winner's schema, and failed physical creation rolls back its metadata row.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php
- Domain
- databases
- Issue type
- Bug
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100