WEBVTT 1 00:00:00.000 --> 00:00:01.580 (Jose)Hi guys and welcome back. 2 00:00:01.580 --> 00:00:03.470 In this video I wanted to tell you a little bit 3 00:00:03.470 --> 00:00:05.980 about the PostgreSQL documentation. 4 00:00:05.980 --> 00:00:07.820 Why you might want to read it, what it contains, 5 00:00:07.820 --> 00:00:10.310 give you a quick primer on its contents, 6 00:00:10.310 --> 00:00:12.050 and yeah, let's get to it. 7 00:00:12.050 --> 00:00:14.870 The PostgreSQL documentation has technical information 8 00:00:14.870 --> 00:00:16.280 about how Postgres works, 9 00:00:16.280 --> 00:00:19.340 including the supported sequel syntax. 10 00:00:19.340 --> 00:00:21.310 Because sequel is the language 11 00:00:21.310 --> 00:00:22.960 that we use to write queries in. 12 00:00:22.960 --> 00:00:25.290 Every different database system like Postgres 13 00:00:25.290 --> 00:00:27.360 or my sequel, Oracle, et cetera, 14 00:00:27.360 --> 00:00:29.620 has a slightly different way of doing things, 15 00:00:29.620 --> 00:00:31.230 so the official Postgres documentation 16 00:00:31.230 --> 00:00:34.630 tells you the way to do things for Postgres. 17 00:00:34.630 --> 00:00:36.810 And the documentation is very extensive, 18 00:00:36.810 --> 00:00:39.950 so don't feel the need to read it like a novel, 19 00:00:39.950 --> 00:00:43.690 but it should be a oft consulted resource. 20 00:00:43.690 --> 00:00:47.560 So, I am always reading the PostgreSQL documentation 21 00:00:47.560 --> 00:00:49.190 or indeed if I'm working with something else, 22 00:00:49.190 --> 00:00:53.150 then that documentation, because it contains how things 23 00:00:53.150 --> 00:00:54.810 really are and what things are, 24 00:00:54.810 --> 00:00:59.690 and they are described properly and fully most of the time. 25 00:00:59.690 --> 00:01:01.580 And really the most important part is that 26 00:01:01.580 --> 00:01:03.580 whenever you're going through a tutorial 27 00:01:03.580 --> 00:01:05.900 or a guide or a course like this one, 28 00:01:05.900 --> 00:01:08.780 well, unfortunately we could be mistaken. 29 00:01:08.780 --> 00:01:12.420 The course creators, we could have some wrong information. 30 00:01:12.420 --> 00:01:14.780 That happens every now and then and also, 31 00:01:14.780 --> 00:01:18.270 the courses can get outdated and the official documentation 32 00:01:18.270 --> 00:01:21.130 does not get outdated or should not get outdated. 33 00:01:21.130 --> 00:01:23.710 It is updated frequently with every new version 34 00:01:23.710 --> 00:01:27.370 of PostgreSQL and they try to keep it up to date. 35 00:01:27.370 --> 00:01:29.630 So, you can access the documentation here 36 00:01:29.630 --> 00:01:34.630 by going to postgresql.org/docs/12/index.html. 37 00:01:35.800 --> 00:01:37.480 This is all linked in the ebook by the way, 38 00:01:37.480 --> 00:01:39.240 and I'm not gonna read the ebook to you right now, 39 00:01:39.240 --> 00:01:41.450 but I just wanted to give you a quick overview. 40 00:01:41.450 --> 00:01:44.970 And so remember the documentation covers different versions, 41 00:01:44.970 --> 00:01:46.990 so do make sure you're on the correct one. 42 00:01:46.990 --> 00:01:48.950 Here on the left you can see the supported version, 43 00:01:48.950 --> 00:01:52.370 so you can click on the one that you're interested in. 44 00:01:52.370 --> 00:01:55.020 Then you've got the table of contents. 45 00:01:55.020 --> 00:01:57.950 Now in the ebook, I cover more or less 46 00:01:57.950 --> 00:02:02.010 what each major part of documentation and talks about 47 00:02:02.010 --> 00:02:05.270 and but really the important parts are the tutorial, 48 00:02:05.270 --> 00:02:06.910 that you can definitely read 49 00:02:06.910 --> 00:02:09.130 and it's gonna give you a different explanation 50 00:02:09.130 --> 00:02:11.110 on how things work with Postgres. 51 00:02:11.110 --> 00:02:13.180 The SQL language part, which talks about 52 00:02:13.180 --> 00:02:16.020 everything that Postgres supports, 53 00:02:16.020 --> 00:02:18.470 and the server administration is for deployments, 54 00:02:18.470 --> 00:02:20.160 and so forth that we haven't covered, 55 00:02:20.160 --> 00:02:23.010 client interfaces is for and the C library 56 00:02:23.010 --> 00:02:25.970 that is used to communicate with the database directly. 57 00:02:25.970 --> 00:02:28.240 Psychopg2 which is the Python library we've used, 58 00:02:28.240 --> 00:02:31.190 actually uses libpq, which is the C library 59 00:02:31.190 --> 00:02:34.530 behind the scenes and that talks to the database, 60 00:02:34.530 --> 00:02:35.930 and so we don't have to learn about this 61 00:02:35.930 --> 00:02:40.350 because we use Python, psychopg2 takes care of this. 62 00:02:40.350 --> 00:02:42.220 So the programming can be pretty interesting, 63 00:02:42.220 --> 00:02:43.880 but we've not done it in the scores, 64 00:02:43.880 --> 00:02:45.780 and also you have to learn some new languages 65 00:02:45.780 --> 00:02:49.640 in order to do it, and for example, a PL/SQL or TclPerl, 66 00:02:49.640 --> 00:02:50.987 you can do some with Python, 67 00:02:50.987 --> 00:02:55.050 but most of the time you're going to see pgSQL being used. 68 00:02:55.050 --> 00:02:57.770 Then you've got the reference which does contain 69 00:02:57.770 --> 00:03:01.370 basically a short hand description of everything 70 00:03:01.370 --> 00:03:04.520 and that PostgreSQL supports including SQL commands, 71 00:03:04.520 --> 00:03:05.830 so that's pretty interesting. 72 00:03:05.830 --> 00:03:07.110 And then you've got some internals 73 00:03:07.110 --> 00:03:09.030 that you're probably not going to be interested in 74 00:03:09.030 --> 00:03:11.730 unless you want to contribute to PostgreSQL. 75 00:03:11.730 --> 00:03:14.970 And then you've got some appendices or appendixes 76 00:03:14.970 --> 00:03:16.680 that uh, can be pretty helpful. 77 00:03:16.680 --> 00:03:18.740 They have a bunch of things like the error codes 78 00:03:18.740 --> 00:03:21.210 and daytime support and so forth. 79 00:03:21.210 --> 00:03:23.650 So again, the ebook has information on all of this 80 00:03:23.650 --> 00:03:26.280 and I have linked in here some of the main parts 81 00:03:26.280 --> 00:03:28.003 of the appendix as well. 82 00:03:29.320 --> 00:03:31.726 In order to find things in the documentation though, 83 00:03:31.726 --> 00:03:34.050 I often go through Google. 84 00:03:34.050 --> 00:03:36.950 If you just type Postgres and the thing 85 00:03:36.950 --> 00:03:37.920 that you're looking for, 86 00:03:37.920 --> 00:03:40.780 it's very likely the documentation is going to come up. 87 00:03:40.780 --> 00:03:44.160 But sometimes it doesn't. And what you end up with, 88 00:03:44.160 --> 00:03:47.371 is some guide or tutorial or often a 89 00:03:47.371 --> 00:03:50.550 cloud PostgreSQL provider's blog 90 00:03:50.550 --> 00:03:52.440 trying to explain to you what things are 91 00:03:52.440 --> 00:03:53.700 and those can be really great. 92 00:03:53.700 --> 00:03:55.790 I mean, I'm making a course on Postgres right here, 93 00:03:55.790 --> 00:03:58.490 so I'm not gonna tell you that those are useless. 94 00:03:58.490 --> 00:04:02.650 But the official documentation is the, 95 00:04:02.650 --> 00:04:04.480 you know, the gospel of truth. 96 00:04:04.480 --> 00:04:07.950 And so if you are looking for a very technical definition 97 00:04:07.950 --> 00:04:10.570 of what something is all the different options 98 00:04:10.570 --> 00:04:12.600 that are supported, et cetera, 99 00:04:12.600 --> 00:04:16.648 then try to avoid those guides and tutorials 100 00:04:16.648 --> 00:04:18.750 and go right to the documentation. 101 00:04:18.750 --> 00:04:21.420 The reason I'm making a course on Postgres as you know, 102 00:04:21.420 --> 00:04:23.520 is to help you understand it, 103 00:04:23.520 --> 00:04:25.806 which is documentation doesn't really do 104 00:04:25.806 --> 00:04:28.560 and but once you're looking for specific things 105 00:04:28.560 --> 00:04:31.290 and you know how things are done, how things are defined, 106 00:04:31.290 --> 00:04:33.178 what arguments things take, et cetera, 107 00:04:33.178 --> 00:04:35.370 their documentation is the best place to go. 108 00:04:35.370 --> 00:04:37.300 Especially because some, as I said earlier, 109 00:04:37.300 --> 00:04:39.823 guides and tutorials can be mistaken. 110 00:04:41.240 --> 00:04:43.290 So, then here's the important part, 111 00:04:43.290 --> 00:04:45.010 which is reading the documentation. 112 00:04:45.010 --> 00:04:46.820 Again, the ebook has all of this information, 113 00:04:46.820 --> 00:04:49.430 but I'll quickly go through it with you. 114 00:04:49.430 --> 00:04:53.560 And so if we go to, for example, drop table as an example, 115 00:04:53.560 --> 00:04:55.010 I'll just bring it into here. 116 00:04:56.030 --> 00:04:58.520 You've gone a bunch of different things going on 117 00:04:58.520 --> 00:04:59.740 in the official documentation. 118 00:04:59.740 --> 00:05:01.670 The first thing is you've got a description 119 00:05:01.670 --> 00:05:03.320 of what you're looking at. Pretty good. 120 00:05:03.320 --> 00:05:06.490 Remember to select the version that you're looking for 121 00:05:06.490 --> 00:05:08.150 in here as well. 122 00:05:08.150 --> 00:05:12.430 Then you've got the synopsis or everything that this command 123 00:05:12.430 --> 00:05:15.580 can take as arguments and how it's constructed. 124 00:05:15.580 --> 00:05:18.288 Anything inside square brackets is optional 125 00:05:18.288 --> 00:05:21.880 and anything that are bold and italics are arguments. 126 00:05:21.880 --> 00:05:23.990 So that means that you're gonna have to type something 127 00:05:23.990 --> 00:05:26.980 in here instead of name and this means 128 00:05:26.980 --> 00:05:28.610 that there can be more things. 129 00:05:28.610 --> 00:05:30.920 And so here we can say drop table, 130 00:05:30.920 --> 00:05:34.430 can optionally take an if exists clause. 131 00:05:34.430 --> 00:05:36.130 Then you're going to type the name of the thing 132 00:05:36.130 --> 00:05:38.430 that you're going to drop as it says here, 133 00:05:38.430 --> 00:05:40.250 and then you can cascade or restricted. 134 00:05:40.250 --> 00:05:42.170 And then down here is going to explain 135 00:05:42.170 --> 00:05:45.030 what every major part of this does. 136 00:05:45.030 --> 00:05:47.660 Here you can say that you can drop multiple tables 137 00:05:47.660 --> 00:05:48.933 at once, if you want. 138 00:05:50.100 --> 00:05:53.950 And the pipe means that you can pick one or the other. 139 00:05:53.950 --> 00:05:57.170 So here you could do drop table if exists, your table name, 140 00:05:57.170 --> 00:05:59.260 cascade or drop table if exists, 141 00:05:59.260 --> 00:06:01.350 your table name, restrict for example. 142 00:06:01.350 --> 00:06:03.220 More things are in the ebook, 143 00:06:03.220 --> 00:06:05.570 so in case you wanna read that. 144 00:06:05.570 --> 00:06:07.420 Then you usually get some examples 145 00:06:07.420 --> 00:06:10.240 in the official documentation, which can be quite helpful. 146 00:06:10.240 --> 00:06:12.890 Although sometimes they don't cover everything 147 00:06:12.890 --> 00:06:14.990 that you can do with a table. For example, 148 00:06:14.990 --> 00:06:17.120 here you've got an example of how to drop a table, 149 00:06:17.120 --> 00:06:19.470 but it doesn't say anything about what restrict and cascade 150 00:06:19.470 --> 00:06:22.040 might affect in a larger example. 151 00:06:22.040 --> 00:06:23.820 So that would be nice. But of course, 152 00:06:23.820 --> 00:06:25.990 the documentation is the technical reference, 153 00:06:25.990 --> 00:06:29.300 it's not a course on Postgres. 154 00:06:29.300 --> 00:06:34.257 Okay. And then you've often got C also, and I recommend that 155 00:06:34.257 --> 00:06:37.030 if you are interested, in just learning and you know, 156 00:06:37.030 --> 00:06:39.380 you wanna discover more about Postgres, 157 00:06:39.380 --> 00:06:40.853 that you do read those. 158 00:06:41.700 --> 00:06:44.940 Often, the official documentation links you away 159 00:06:44.940 --> 00:06:46.940 to other stuff. For example, 160 00:06:46.940 --> 00:06:49.550 here we've got automatically drop objects 161 00:06:49.550 --> 00:06:52.853 that depend on a table, blah-blah-blah see section 514. 162 00:06:53.800 --> 00:06:57.080 And it's usually a good idea to give it a look, 163 00:06:57.080 --> 00:07:00.310 see what it's talking about because that can give you 164 00:07:00.310 --> 00:07:03.540 a better global view on what's going on. 165 00:07:03.540 --> 00:07:06.660 However, pages linked to other pages, 166 00:07:06.660 --> 00:07:07.930 that link to other pages. 167 00:07:07.930 --> 00:07:10.210 And eventually you can end up in this rabbit hole 168 00:07:10.210 --> 00:07:12.380 of reading through documentation and eventually 169 00:07:12.380 --> 00:07:14.210 you're not really sure if what you're reading 170 00:07:14.210 --> 00:07:16.340 really applies to you or not anymore. 171 00:07:16.340 --> 00:07:18.660 And so I recommend that you look 172 00:07:18.660 --> 00:07:20.490 at the thing that you're interested in 173 00:07:20.490 --> 00:07:25.190 and briefly one page away, see what's there more or less, 174 00:07:25.190 --> 00:07:27.490 but don't go into too much detail. 175 00:07:27.490 --> 00:07:30.480 You can always come back to it and learn more later on. 176 00:07:30.480 --> 00:07:32.410 So don't spend too much time, you know, 177 00:07:32.410 --> 00:07:34.530 reading through every page because, 178 00:07:34.530 --> 00:07:35.520 you're just going to forget everything 179 00:07:35.520 --> 00:07:37.670 and it's not going to be that useful for you. 180 00:07:37.670 --> 00:07:39.370 Okay. So, that's about it. 181 00:07:39.370 --> 00:07:41.680 As usually in the ebook I've got some of these references, 182 00:07:41.680 --> 00:07:43.320 down there that you can check out. 183 00:07:43.320 --> 00:07:45.999 Um, so thank you for joining me for this video. 184 00:07:45.999 --> 00:07:48.330 I hope you've sort of learned a bit more 185 00:07:48.330 --> 00:07:50.100 about what the documentation is. 186 00:07:50.100 --> 00:07:51.930 And by reading the ebook you can see the different 187 00:07:51.930 --> 00:07:54.120 parts there and what they're for. 188 00:07:54.120 --> 00:07:56.180 Don't be afraid of documentation. 189 00:07:56.180 --> 00:07:59.180 You need to read it in order to get comfortable with it, 190 00:07:59.180 --> 00:08:00.830 so that you will read it more often. 191 00:08:00.830 --> 00:08:03.185 So it's going to be uncomfortable for the beginning, 192 00:08:03.185 --> 00:08:05.460 but I'm sure you can do it. 193 00:08:05.460 --> 00:08:06.810 Alright, thank you guys for joining me, 194 00:08:06.810 --> 00:08:07.940 thanks for watching this video, 195 00:08:07.940 --> 00:08:09.390 I'll see you in the next one.