-: (Jose)Hi guys and welcome back.
In this video I wanted to tell you a little bit
about the PostgreSQL documentation.
Why you might want to read it, what it contains,
give you a quick primer on its contents,
and yeah, let's get to it.
The PostgreSQL documentation has technical information
about how Postgres works,
including the supported sequel syntax.
Because sequel is the language
that we use to write queries in.
Every different database system like Postgres
or my sequel, Oracle, et cetera,
has a slightly different way of doing things,
so the official Postgres documentation
tells you the way to do things for Postgres.
And the documentation is very extensive,
so don't feel the need to read it like a novel,
but it should be a oft consulted resource.
So, I am always reading the PostgreSQL documentation
or indeed if I'm working with something else,
then that documentation, because it contains how things
really are and what things are,
and they are described properly and fully most of the time.
And really the most important part is that
whenever you're going through a tutorial
or a guide or a course like this one,
well, unfortunately we could be mistaken.
The course creators, we could have some wrong information.
That happens every now and then and also,
the courses can get outdated and the official documentation
does not get outdated or should not get outdated.
It is updated frequently with every new version
of PostgreSQL and they try to keep it up to date.
So, you can access the documentation here
by going to postgresql.org/docs/12/index.html.
This is all linked in the ebook by the way,
and I'm not gonna read the ebook to you right now,
but I just wanted to give you a quick overview.
And so remember the documentation covers different versions,
so do make sure you're on the correct one.
Here on the left you can see the supported version,
so you can click on the one that you're interested in.
Then you've got the table of contents.
Now in the ebook, I cover more or less
what each major part of documentation and talks about
and but really the important parts are the tutorial,
that you can definitely read
and it's gonna give you a different explanation
on how things work with Postgres.
The SQL language part, which talks about
everything that Postgres supports,
and the server administration is for deployments,
and so forth that we haven't covered,
client interfaces is for and the C library
that is used to communicate with the database directly.
Psychopg2 which is the Python library we've used,
actually uses libpq, which is the C library
behind the scenes and that talks to the database,
and so we don't have to learn about this
because we use Python, psychopg2 takes care of this.
So the programming can be pretty interesting,
but we've not done it in the scores,
and also you have to learn some new languages
in order to do it, and for example, a PL/SQL or TclPerl,
you can do some with Python,
but most of the time you're going to see pgSQL being used.
Then you've got the reference which does contain
basically a short hand description of everything
and that PostgreSQL supports including SQL commands,
so that's pretty interesting.
And then you've got some internals
that you're probably not going to be interested in
unless you want to contribute to PostgreSQL.
And then you've got some appendices or appendixes
that uh, can be pretty helpful.
They have a bunch of things like the error codes
and daytime support and so forth.
So again, the ebook has information on all of this
and I have linked in here some of the main parts
of the appendix as well.
In order to find things in the documentation though,
I often go through Google.
If you just type Postgres and the thing
that you're looking for,
it's very likely the documentation is going to come up.
But sometimes it doesn't. And what you end up with,
is some guide or tutorial or often a
cloud PostgreSQL provider's blog
trying to explain to you what things are
and those can be really great.
I mean, I'm making a course on Postgres right here,
so I'm not gonna tell you that those are useless.
But the official documentation is the,
you know, the gospel of truth.
And so if you are looking for a very technical definition
of what something is all the different options
that are supported, et cetera,
then try to avoid those guides and tutorials
and go right to the documentation.
The reason I'm making a course on Postgres as you know,
is to help you understand it,
which is documentation doesn't really do
and but once you're looking for specific things
and you know how things are done, how things are defined,
what arguments things take, et cetera,
their documentation is the best place to go.
Especially because some, as I said earlier,
guides and tutorials can be mistaken.
So, then here's the important part,
which is reading the documentation.
Again, the ebook has all of this information,
but I'll quickly go through it with you.
And so if we go to, for example, drop table as an example,
I'll just bring it into here.
You've gone a bunch of different things going on
in the official documentation.
The first thing is you've got a description
of what you're looking at. Pretty good.
Remember to select the version that you're looking for
in here as well.
Then you've got the synopsis or everything that this command
can take as arguments and how it's constructed.
Anything inside square brackets is optional
and anything that are bold and italics are arguments.
So that means that you're gonna have to type something
in here instead of name and this means
that there can be more things.
And so here we can say drop table,
can optionally take an if exists clause.
Then you're going to type the name of the thing
that you're going to drop as it says here,
and then you can cascade or restricted.
And then down here is going to explain
what every major part of this does.
Here you can say that you can drop multiple tables
at once, if you want.
And the pipe means that you can pick one or the other.
So here you could do drop table if exists, your table name,
cascade or drop table if exists,
your table name, restrict for example.
More things are in the ebook,
so in case you wanna read that.
Then you usually get some examples
in the official documentation, which can be quite helpful.
Although sometimes they don't cover everything
that you can do with a table. For example,
here you've got an example of how to drop a table,
but it doesn't say anything about what restrict and cascade
might affect in a larger example.
So that would be nice. But of course,
the documentation is the technical reference,
it's not a course on Postgres.
Okay. And then you've often got C also, and I recommend that
if you are interested, in just learning and you know,
you wanna discover more about Postgres,
that you do read those.
Often, the official documentation links you away
to other stuff. For example,
here we've got automatically drop objects
that depend on a table, blah-blah-blah see section 514.
And it's usually a good idea to give it a look,
see what it's talking about because that can give you
a better global view on what's going on.
However, pages linked to other pages,
that link to other pages.
And eventually you can end up in this rabbit hole
of reading through documentation and eventually
you're not really sure if what you're reading
really applies to you or not anymore.
And so I recommend that you look
at the thing that you're interested in
and briefly one page away, see what's there more or less,
but don't go into too much detail.
You can always come back to it and learn more later on.
So don't spend too much time, you know,
reading through every page because,
you're just going to forget everything
and it's not going to be that useful for you.
Okay. So, that's about it.
As usually in the ebook I've got some of these references,
down there that you can check out.
Um, so thank you for joining me for this video.
I hope you've sort of learned a bit more
about what the documentation is.
And by reading the ebook you can see the different
parts there and what they're for.
Don't be afraid of documentation.
You need to read it in order to get comfortable with it,
so that you will read it more often.
So it's going to be uncomfortable for the beginning,
but I'm sure you can do it.
Alright, thank you guys for joining me,
thanks for watching this video,
I'll see you in the next one.