Thanks to Grant Fritchey (https://www.scarydba.com/), PGSQL Phriday #006 is about the things you wish you knew while learning Postgres.
I could have created a very easy post with quick tips on psql, like how to
disable this horrible pager the “ancient” Postgres contributors insist on
keeping on by default (BTW, it’s \pset pager off, you’re welcome, you’ll thank me later),
but as I wrote an entire website on that exact topic,
I thought I needed to find something else.
So here is my topic: how to use the Postgres documentation! Yes, that documentation content is great, but no, that documentation is not easy to navigate at first.
A documentation to rule them all
Contrary to some projects which decided to create different documentation pages depending on the audience, Postgres has only one documentation. It means that whether you’re a developer, a DBA, or a simple Postgres user you will end up on the same webpage, but not all sections of the documentation will be that relevant to you.
Common things you’re all interested in
First small important information: for each page, you will find in the header direct link to previous and next versions of the same page, so that you will easily find the one matching the version you’re working with.
Another important piece of information: the search engine sucks. Don’t rely on it. I’m sorry, but I have to say the truth.
There is a great Glossary explaining technical terms. It is sadly buried in the appendices…
For a DBA
Let me begin with DBAs as they’re always usually forgotten…
DBAs are interested in the following topics: installing Postgres, managing Postgres, maintaining Postgres, configuring Postgres, monitoring Postgres. the most important part of the documentation that any dBA should have read cover to cover is part III. You will find here the following very important topics:
- How to install Postgres
- How to upgrade Postgres
- How to configure Postgres
- How to perform routine maintenance
- How to backup and restore Postgres (even though I still recommend pgBackRest)
- Monitoring Postgres
- High availability and Logical replication
So, apart from that very important chapter in the documentation, there are some parts here and there that can be very interesting for a DBA here. They are:
- System administration functions
- SQL, client and server apps reference
- The system catalog
- The release notes (that you should read before each upgrade)
For a software developer
Developers may need the documentation to write their SQL queries. They will find everything in chapters 4, 5, 6 and 7. If you’re a developer and you think you know SQL, please reconsider that assumption. No one really knows SQL…
In order to develop for Postgres, you will need to consult the documentation on the following topics:
If you want to create stored functions and procedures, you will be interested in SQL function, PL/pgSQL and Other languages as PL/Tcl, PL/Perl, PL/Python.
Postgres users
Postgres users will very likely need a great SQL client. What a coincidence! We have psql in Postgres!
So, I guess the only documentation a Postgres user needs is the psql. That should be the one and only documentation page needed!
Postgres documentation is good and bad
Postgres documentation is good because everything is in it, but it is bad because it is difficult at first to find things there. I remember a custoer once saying me I was not a real Postgres expert because I was always checking the documentation. I think that I was actually a good expert because I know where to find the information in the documentation!