Inconsistent preference for singular/plural in the docs

[evolkmann]

Summary

The documentation for v5 gives recommentations how users shall design their schema and name database objects. The docs are inconsistent and sometimes recommend singular (e.g. "vehicle") and sometimes plural (e.g. "vehicles").

Additional context

• Plural Example: https://github.com/graphile/crystal/blob/main/postgraphile/website/postgraphile/required-knowledge.md?plain=1#L57-L58
• Singular Example: https://github.com/graphile/crystal/blob/main/postgraphile/website/postgraphile/postgresql-schema-design.mdx?plain=1#L144 (more complex case "people/person")

It might be worth scanning the whole docs to make sure this is consistent.

If I remember correctly, the old advice (from v4 or the Starter) was to use singular, at least that is what I did in a couple of projects ever since 😅

PS: Looking forward to starting a brand new project with v5 in the next weeks (also with worker and migrate) – really happy with all your work, keep it up!

[benjie]

Thanks for the feedback! The advice since I've ran the project (v4+, Starter, etc) is plural since the PostgreSQL built-ins (such as user) use singular, so by using plural you will not conflict with them. (Also, for me "select * from users" makes more sense because you're selecting from a collection of users, not from a single user.) But I don't particularly care. The vast majority of the documentation uses plural for this reason; however the schema design guide was written by Caleb, who prefers (preferred?) singular, and there are other user-contributed pages that may or may not use singular too.

It doesn't particularly matter if you use plural or singular, so I don't think our docs need to be consistent on this?

We do document this mild preference on the required knowledge page, but only in a passing sentence - perhaps we should add a "conventions" document?

The word user is reserved, among others

If you want to call your table user you need to escape it; e.g.

create table "user" ( ... );

Here's a full list of reserved keywords: https://www.postgresql.org/docs/current/sql-keywords-appendix.html

Most PostgreSQL keywords are singular, which is why Benjie prefers to use plurals when naming tables as it helps avoid potential keyword clashes.
-- https://postgraphile.org/postgraphile/next/required-knowledge/#the-word-user-is-reserved-among-others

Caleb's schema design guide contains this counterpoint:

We prefer singular identifiers like forum_example.person over
forum_example.people because when you create a table, it is like you are
creating a class in an object-oriented language. Classes have singular names
like “Person” while collections will often have plural names like “People.”
Table as a class is a better analogy than table as a collection because
Postgres itself will internally call tables “classes.”

Perhaps adding a caveat near the beginning saying that the guide follows a different style might be wise.