CODEWITHSUNDEEP
postgresqlcommentspsql
Ben Millwood
Ben Millwood

Reputation: 7001

Which comments are included in the most common psql describe commands?

I like making the lives of my future self and collaborators easier by using COMMENT ON to add comments on database objects. People can then see them when they're exploring the schema with \d+ and \df+ and so on.

However, some objects can accept comments, but psql won't display them where I would expect developers to typically go to learn about an object. For example, I can do COMMENT ON POLICY ... to add comments to an RLS policy, but they don't show up on \d+ or \dp+ for the table, which are the commands I'd normally use to inspect RLS policies.

What comments can I use and reasonably expect psql to show in an easily-accessible place?

Upvotes: 1

Views: 84

Answers (1)

Ben Millwood
Ben Millwood

Reputation: 7001

  • COMMENT ON COLUMN is visible in \d+ for the relation.
  • COMMENT ON FUNCTION is visible in \df+ for the function. Since functions are stored as text, you can also include code comments in functions, and they will be visible to someone reading the function too.
  • COMMENT ON SCHEMA is visible in \dn+
  • COMMENT ON ROLE is visible in \dg+
  • COMMENT ON TYPE is visible in \dT (unlike the other examples, you don't need the +)
  • COMMENT ON TABLE or VIEW or MATERIALIZED VIEW etc. are visible in the listing of objects you get when you run \d+ with no arguments. They don't seem to be in \d+ for the object itself.
  • COMMENT ON CONSTRAINT is visible in \dd for the constraint name, although there's ~no other reason to look at \dd, so I don't think this is worth much.
  • As mentioned in the question, COMMENT ON POLICY doesn't appear to be visible anywhere (or maybe it's in \dd, but if so I don't know how to find it).

There's obviously many more of these, but these are the notes I've made so far. Feel free to edit in more.

Upvotes: 1

Related Questions