# .single() vs maybeSingle(): missing rows are not errors

`.single()` is an assertion: exactly one row must come back. Agents use it for "get the user's profile" and then handle the not-found case as an exception, or worse, do not handle it and crash. If the row might legitimately not exist, that is not exceptional.

## Symptom to cause to confirmation to fix

1. Identify whether absence is normal. "Fetch the profile for a new user" can legitimately return nothing. That is maybeSingle, returning null, which your code handles as a value.
2. Keep .single() for genuine invariants: "fetch the row we just inserted" or "fetch by primary key after confirming existence". There, zero rows means a bug, and the throw is the right behavior.
3. More than one row also throws under .single(). If your filter is not unique, that is a data or query bug, not a reason to switch to maybeSingle. Fix the filter or the data.
4. Handle the null from maybeSingle explicitly at the call site. "Profile not found, show onboarding" is business logic; it belongs in the open, not in a catch block.
5. In TypeScript, the return types differ. Let the type checker enforce the handling: a maybeSingle result must be null-checked before property access.

## Verification

Query for a missing row and confirm maybeSingle returns null with no error. Query for a missing row with .single() and confirm it throws. Both behaviors are correct; the skill is choosing the right one per call site.