Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation showing how different TableSchemas relates to an actual sql schema #311

Open
abigailalice opened this issue Mar 5, 2024 · 0 comments

Comments

@abigailalice
Copy link
Contributor

abigailalice commented Mar 5, 2024

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:

  1. The ability to use nested records within table definitions, which is kind of alluded to, but which I think could be spelled out better.
  2. For MaybeTable, that the column which stores the tag needs should have sql type BOOL, but only allows values TRUE and NULL, for the isJust and isNothing case respectively (I think, that confused me, but my own experience with it and the type of nameMaybeTable makes me think that's right?). If used with namesFromLabelsWith rather than nameMaybeTable, the column for the tag has name ["isJust"], while the names for any columns contained in the Just case have "Just" prepended to the NonEmpty String which represents the column names of the columns stored in the Just case, passed to the naming function. If the type stored within the MaybeTable is a base type the name is just "Just".
  3. For EitherTable, the type for the tag column should be BOOL, with FALSE corresponding to the Left case and TRUE to the Right. The tag columns name is "isRight", and the columns stored within the Left and Right constructors have "Left" and "Right" prepended to the NonEmpty String, as in (2).
  4. For Haskell tuples, are given names like "_1", "_2", when stored in a table.
  5. 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.
  6. 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 type BOOL, but only take values of TRUE or NULL, similar to MaybeTable

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants