Rethink `Unique`

[parsonsmatt]

The issue in #1236 illustrates a need to rethink how we handle Uniques.

Ultimately, the problem comes down to conflating two uses of the type:

1. Specifying a unique key for retrieval (eg getBy :: Unique rec -> m (Maybe (Entity rec)))
2. Specifying a uniqueness constraint for conflict (eg upsertBy).

The EntityField rec typ type works great for talking about the fields on an entity, so it seems like we might copy that design.

-- let's factor this out of PersistEntity while we're at it
class PersistEntity rec => PersistEntityUnique rec where
    data UniqueConstraint rec :: Type -> Type

data Unique rec where
    Unique :: UniqueConstraint rec typ -> typ -> Unique rec

it would be nice if we could somehow capture the actual EntityFields in the UniqueConstraint type, too. Then we could reuse things like persistFieldDef :: EntityField rec typ -> FieldDef. But, we can't promote data family constructors, as that "requires dependent types" for some reason.

[parsonsmatt]

#1090 is related, as is #985

Ideally, Key and Unique would be unified, or at least have some method to go from Key rec -> Unique rec.

[hdgarrood]

Is #906 related to this at all? I'm not sure how unified Unique and Primary are at the moment.

[parsonsmatt]

They are completely disparate at the moment, even though the entity's Key should really be considered a Unique.

[parsonsmatt]

OK, let's think about this 🤔

Right now we've got

class PersistEntity a where
    -- ... snip ...
    data Unique a 
    -- ... snip ...

instance PersistEntity User where
    data Unique User 
        = UniqueUserEmail Email

This works fine for getBy :: Unique a -> DB (Maybe (Entity a)) - we call getBy (UniqueUserEmail "asdfasdf") and it's cool. But it's less fine when we're trying to write upsertBy :: Unique a -> a -> [Update a] -> DB (Entity a) - the Unique a has no guarantee that it matches what we're trying to insert, and it'd be weird to do otherwise. Ideally, with upsertBy, we'd be specifying which unique key, not a complete unique key.

Additionally, a Unique key must refer to the EntityField type, and ideally, have some notion of how to combine those fields to produce that unique constraint.

Also it's super annoying that Key and Unique are distinct at all. They do the exact same thing. In current persistent, the only difference is that a Key a is used as a surrogate key, and isn't present on an a, whereas a Unique a is present on an a (as witnessed by recordToUniques :: a -> [Unique a]). But then a Primary natural key definitely exists on the thing, but it's a Key and not a Unique for some reason (#1090).

🤔

As a constraint, I'd like to prevent as much breaking as possible. Which means that Key ~ Unique, probably - allowing you to write get $ UniqueUserEmail "asdfasdf" and getBy $ UserKey asdfasdf.

Which means that all existing constructors should still be usable. Which either means we'll have to put everything else kinda before this, or write pattern synonyms for them.

[parsonsmatt]

Also related to #985

A small step that would help is if a Primary key is specified (eg we have a natural key), then we also generate a data constructor for it.

mkPersist sqlSettings [persistLowerCase|

User
    name Text
    Primary name
|]

-- ====>

instance PersistEntity User where
    data Unique User 
        = UniqueUserKey (Key User)

This should be relatively straightforward to add. I'll make an issue and assign it to a 2.14, since it'll be a breaking change.