Retry safely.
Return the existing relationship when the request repeats.
The onboarding code had passed its tests. Then the operator guide placed idempotency beside tenant transfer—and proved our database could not represent the procedure we had documented.
One section promised idempotent onboarding. Another explained how an identity could move between tenants. The schema allowed only one row for an identity-provider subject anywhere, so the old relationship could not remain as history while a new one became active.
Return the existing relationship when the request repeats.
Preserve history while establishing a new active relationship.
An instruction to delete the old row before creating the new one would erase history and create a failure window. If creation failed after deletion, the identity would belong nowhere. Operator discipline could not turn that into an atomic transition.
We added lifecycle status and replaced global uniqueness with a partial unique index. PostgreSQL supports enforcing uniqueness only among rows that satisfy an index predicate. The database could now retain historical relationships while rejecting two active owners for the same subject.
The transfer still required a transaction and concurrency tests. The index was an invariant, not a complete workflow.
Local tests and production can use identities with different privileges. We expanded verification to prove idempotent retries, retained history, rejection of a second active row, rollback after interruption, and behavior through a production-like role.
A runbook must explain time, retries, reversal, and partial failure.
A transfer should not require deleting the evidence of its prior state.
The database—not operator memory—rejects two active owners.
A green result matters only when the test role can fail appropriately.
PostgreSQL: Partial Indexes
PostgreSQL: Constraints
PostgreSQL: Transactions
Educational material only. This dated CareFlow implementation is not a universal identity or database prescription.
A narrated account of the contradiction, the unsafe workaround, and the database invariant that made transfer enforceable.
How operational documentation exposed a lifecycle the original schema could not represent.