Basic tutorial seems out of date

[tysonzero]

It uses leftJoin which the docs specify as not recommended in favor of optionalRestrict, optionalRestrict doesn't mention anything about being not recommended but I get the impression that the arrow syntax in general is semi-deprecated in favor of the monadic syntax.

Similarly it uses FieldNullable extensively but the "Working with NULL" section of Opaleye.Field mentions you should be using Opaleye.MaybeFields instead, although that itself also confuses me as for individual nullable columns it seems like the former is more appropriate, even if the latter will work nicely for outer joins.

This is less of an "out of date" thing but the newtype section being so short and not tied into the rest of it is also making it rather unclear to me what the "idiomatic" way to work with those newtypes is in less trivial situations. For example I'm currently using ors instead of in_ so that I can use the .=== machinery. I'm also trying to work with nullable type-safe foreign keys and it's not obvious to me how to preserve the type safety, as .=== doesn't allow nulls (but does allow MaybeFields?) and matchNullable doesn't have the Default machinery.

[tomjaguarpaw]

Yes, you're right.

1. We should no longer be mentioning leftJoin in the tutorial, but use optional instead.
2. leftJoin should recommend optional first (and come with an example) and optionalRestrict second.

Regarding foreign keys, maybe it would be best to start a new issue. I'm surprised that foreign keys can be nullable. What's the use case for that?

[tomjaguarpaw]

Points 1 and 2 will be addressed by #600

[tomjaguarpaw]

Do please elaborate on the remaining parts, which I think are FieldNullable and particularly its use in newtypes. (A new issue might be good.)

[tysonzero]

Occasionally many-to-one-or-none relations come up, and as far as I can tell the most obvious way to model them is via an optional foreign key, e.g. a post author where the post can be anonymous.

From a quick google I see mixed opinions on whether nullable fkeys are bad practice or not, with some pointing out it violates a certain type of normal form and others saying they can be more pragmatic.

Funnily enough though to your point I did end up getting rid of the nullable foreign key for now, and I may later replace it with a many-to-many table, so perhaps they are more avoidable than I give them credit for.

If we do go down the route of not really encouraging nullable foreign keys the one additional thing I would say is that it makes #591 more useful, as one of the reasons I was avoiding a link table is because it prevents me from storing the related object(s) on the type itself as I'd need missingTableField to make it work.

[tomjaguarpaw]

From a quick google I see mixed opinions on whether nullable fkeys are bad practice or not

I think if people use them then we should support them (regardless of whether they're bad practice) although we don't necessarily need to make it easy to use them, just possible.