rel8
rel8 copied to clipboard
Improve documentation showing how different TableSchemas relates to an actual sql schema
I don't think the documentation defines how Haskell datatypes map to SQL tables especially well in non-trivial cases. I've really only looked into these issues as I encounter them, so I'm not 100% sure this is all right, but things I think which need to be made clear, assuming I've understood them correctly:
- The ability to use nested records within table definitions, which is kind of alluded to, but which I think could be spelled out better.
- For
MaybeTable
, that the column which stores the tag needs should have sql typeBOOL
, but only allows valuesTRUE
andNULL
, for theisJust
andisNothing
case respectively (I think, that confused me, but my own experience with it and the type ofnameMaybeTable
makes me think that's right?). If used withnamesFromLabelsWith
rather thannameMaybeTable
, the column for the tag has name["isJust"]
, while the names for any columns contained in theJust
case have"Just"
prepended to theNonEmpty String
which represents the column names of the columns stored in theJust
case, passed to the naming function. If the type stored within theMaybeTable
is a base type the name is just"Just"
. - For
EitherTable
, the type for the tag column should beBOOL
, withFALSE
corresponding to theLeft
case andTRUE
to theRight
. The tag columns name is"isRight"
, and the columns stored within theLeft
andRight
constructors have"Left"
and"Right"
prepended to theNonEmpty String
, as in (2). - For Haskell tuples, are given names like "_1", "_2", when stored in a table.
- For the
ADT
type, the column storing the tag has name "tag", with type "TEXT NOT NULL", and columns stored within each constructor have the constructor name prepended to the column names, the same as for Haskell's standard sum types, and then "_1", "_2", ..., for each argument stored in the constructor. - For
TheseTable
there are two columns for tags, named "hereTag" and "thereTag", which are used to state whether the left or right types are present, which each have sql typeBOOL
, but only take values ofTRUE
orNULL
, similar toMaybeTable
I've only really used ADTs and nested records within my own tables, and mostly got the rest of this just from playing with showQuery
, so I'm not 100% sure it's right. But even if it is it's all still kind of wordy to the point I think someone basically needs to already have figured things out for themselves for the meaning to get across.
So I think it might be worthwhile for their to be a separate section in the documentation the way the ADTs themselves have, going over the simple case of a user just using nameFromLabels
, also showing the matching sql schema with column names and types, and making note that there are functions to override the naming schema if desired. I'm willing to try writing something myself if other people agree this should be better documented, but it would be a sizeable addition, so thought I'd see what anyone else thought first.