sql_inheritance: Tutorial about using postgreSQL Inheritance

[falkmielke]

Description

I was evaluating whether to overhaul part of our main database by using inheritance.
This required some sandbox data to test specific cases.
I figured it might be useful to immediately write up a tutorial notebook.
I doubt that many people at INBO will have immediate use for it; however, I did not find many other practical tutorials which explore the details and implications for our specific use case.

Task list

• My tutorial or article is placed in a subfolder of tutorials/content/
• The novel tutorial has a meaningful name, in relation to the content of the tutorial.
• The filename of my tutorial or article is index.md. In case of an Rmarkdown tutorial I have knitted my index.Rmd to index.md (both files are pushed to the repo).
• yaml header:
  • (recommended) I am included as author in the authors yaml tag, using [MY_AUTHOR_ID]. An author information file exists in <tutorials>/data/authors/<author>.toml.
  • I have added categories to the YAML header and my category tags are from the list of categories.
  • I have included meaningful and applicable tags (i.e. keywords) in the YAML header to improve the visibility of the new tutorial (see the tags listed in the tutorials website side bar).
  • The date is in format YYYY-MM-DD and adjusted.
• (recommended) I have previewed this PR locally (see steps below; ask previous contributors for help) and confirmed that the new content renders as expected.

Previewing the pull request

Thanks to GitHub Actions, an artifact (=zip file) of the rendered website is automatically created for each pull request.
This provides a way to preview how these updates will look on the website, useful to contributors and reviewers.

Instructions to preview the updated website

1. On the PR page, you can find a "details" link under "checks - On PR, build the site and ...". Go there, click on the top link in the left sidebar ("Summary"), and download the generated artifact at the bottom of the page.
2. Decompress it into a target directory, e.g. Downloads/tutorials_preview.
3. To preview the website, use a program which can serve http sites on your local machine. One such option is the servr package in R: & '\C:\Program Files\R\R-4.4.2\bin\Rscript.exe' -e "servr::httd('./tutorials_preview')" -p8887 (make sure to adjust the path to your Rscript.exe; on Linux, simply use Rscript -e [...]).
4. Point your browser to http://localhost:8887.
5. Review the updated website. As a contributor, you can push extra commits to update the PR. As a reviewer, you can accept/refuse/comment the PR.

Note: for step 3, you can use any other simple HTTP server to serve the current directory, e.g. Python http.server: python -m http.server 8887 --bind localhost --directory path/to/tutorials_preview

Alternative: Locally Building the Site

Alternatively, you can build the entire site locally (see the README for instructions); the Hugo preview server will update changes on the fly.
This requires Hugo to be installed on your computer.

[ElsLommelen]

Interesting, and nicely written! I just added some minor suggestions, I hope they are useful (otherwise feel free to ignore them).
(I'll let you have a look first and I'll approve when you are finished, as I recently encountered some situations where the approval had to be done again after new commits were added.)

[ElsLommelen]

What about unique primary keys for these inherited tables? Do they need an extra PK, or is it enough to inherit the PK from table Activities? You may want to add the PK in the earlier example to demonstrate this more clearly.

[falkmielke]

This is well observed, and a relevant matter, yet I personally think it is out of the scope of this simple introduction.
Primary key setup is completely up to the database designer. And I cannot claim any superior experience to justify any advice on the matter.
At any rate: the primary key which is inherited works just fine, and should be used (since there strictly is only one real pk available per table; yet I do not remember if I tested adding another one in the inherited table).
I personally tend to add another unique identifier per child table. But I actually never use it.

[ElsLommelen]

Why is the output missing here?

[falkmielke]

Indeed. I added an explicit --| output: true in the quarto document.

[ElsLommelen]

It could be useful to mention how these tables could be updated in an easy way: the below part is titled advanced and it may discourage readers that are less familiar with databases but want to incorporate the inheritance for a better database structure. While it might not be needed to demonstrate this all in code, you may want to mention in one sentense that this update could be performed in table PushUps (if true)?

[falkmielke]

Yes, good observation and suggestion. Thank you! I added a sentence (commit in prep).

[falkmielke]

I inserted an R tip here which I have been using as a workaround for lacking R functionality.

[falkmielke]

Thank you for the review, @ElsLommelen !
I have adjusted the text and incorporated your suggestions, except the extended discussion of primary keys (see comment).

From my side, this is ready to merge; feel free to proceed.

[ElsLommelen]

Apart from a small typo, it looks fine!