@nullability smart tag

[benjie]

Using this to document a discussion @jemgillam and I just had.

I'm working on the "V4" preset that gives V5 compatibility with V4. Part of this requires us to support V4 smart tags that are being replaced in V5 (mostly by behavior). Whilst going over that we needed to figure out where the various "smart tags" apply; in particular because the schema build phase is now split into gathering and building the Data Sources, and then building the schema, we need to know where the tags apply.

@omit and @simpleCollections clearly belong to the GraphQL schema, even if we have -insert (@omit create) we should still support insert in the Data Source so that plugins can use it, we simply won't expose that capability via the GraphQL schema.

On the other hand, @primaryKey, @foreignKey and @unique clearly belong to the Data Source - these are "fake constraints" and should behave as if the constraints had been defined on the table in the first place. The schema build will then not differentiate between whether these constraints were real constraints or came from smart tags.

What we got stuck on was @notNull. We had it in the "fake constraints" section in the docs, but should it really change the Data Sources? What does that even mean, really? Maybe it's more of a GraphQL presentational thing...?

After much discussion, it turns out that we actually have a larger problem around nullability that we attempted to fix with makeChangeNullabilityPlugin in V4 but didn't handle well for things like lists. At the GraphQL Working Group recently we've been discussing client controlled nullability (CCN) which has somewhat similar concerns.

So we've concluded that we actually need two smart tags:

@notNull - a "fake constraint" that applies directly to the Data Sources and is not read by the GraphQL schema build phase. Boolean.

@nullability - a presentational smart tag that only affects the exposed GraphQL schema. Interestingly this is a string, the syntax for which is similar to what CCN uses - effectively ! to mark something non-nullable, ? to mark it nullable, and `` to keep it as whatever it was before. Then for nested lists we use parenthesis. For example a non-nullable list of nullable lists of non-nullable ints would be [[!]?]!.

I've not written the code for @nullability yet (if you want to take that on, ping me here!) but at least the problem is somewhat solved now. Well, that is until we realise that the nullability presentation of a column could be different for create versus update versus output...