Обсуждение: Tutorial from Chapter 2.1

The following documentation comment has been logged on the website:

Page: https://www.postgresql.org/docs/17/tutorial-sql-intro.html
Description:

Hi!
I am in the process of studying your DBMS. And everything was fine with me
until the moment when the tutorial in Chapter 2.1, which is proposed needed
to be compiled. And it would be fine if I was originally a proponent of the
"download sources, compile" algorithm, but I'm a simple user who's just
learning.

What is this complication for? And it would seem that there is only one
additional command - make. But there is no compiled or source of tutorial in
the Docker image, and it was not supposed to be for binaries on Windows.
And now I have to,
- firstly, look for the source code of the tutorial,
- secondly, determine the path of where the source code should be in an
already compiled application, or compile the whole application from scratch,
- thirdly, compile and be sure that the compilation will be successful,
- and fourth, finally run the tutorial files and continue studying.
Isn't that heresy?

What prevented you from including the tutorial sources in the already
compiled versions? What prevented you to make an option during installation,
where it is suggested to install pgAdmin and 3 more applications, actually
the tutorial itself? What prevented you add it as an option when starting
postgres or psql --start-tutorial in order to upload materials to the
database?

Fix it so that access to the tutorial (since you have it) becomes convenient
for ALL people with sources, binaries, installers, archives and any other
supplies.

Fix it so that access to the tutorial (since you have it) becomes convenient
for ALL people with sources, binaries, installers, archives and any other
supplies.

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> Well, the main issue is the people who write the documentation and code the
> software only directly support installing it from source code.  Third-party
> packagers take over when it comes to producing binaries.  You would need to
> convince them to change their ways.  This documentation feedback form is
> unlikely to be something they see.

Yeah ... it'd be nice if packagers created a postgresql-tutorial
subpackage with those files, but the heavy lifting would all need
to be done by the packagers, not the core project.  I'm not really
surprised that none of them have done so.  There's not that much
incremental benefit from being able to reproduce the tutorial
chapter's examples locally.

Possibly we should reword the tutorial intro a bit, to the effect
that you can follow along with the examples if you have a source
tree at hand.  (Sadly, that's not going to be very many novices
these days.)

            regards, tom lane

Possibly we should reword the tutorial intro a bit, to the effect
that you can follow along with the examples if you have a source
tree at hand.  (Sadly, that's not going to be very many novices
these days.)

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Sunday, August 10, 2025, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Possibly we should reword the tutorial intro a bit, to the effect
>> that you can follow along with the examples if you have a source
>> tree at hand.  (Sadly, that's not going to be very many novices
>> these days.)

> I’d rather remove it from the docs and make a home for it in the wiki or,
> probably better, have a separate git repository that they could clone.

Making it buildable standalone would be a significant investment
of effort I fear.  Right now it's dependent on the autoconf/makefile
infrastructure of the surrounding Postgres source tree.

The other problem would be keeping it in sync with the tutorial
docs proper.  I guess we could pull those out of the main
documentation altogether, and make "the Postgres tutorial" into
a fully standalone project.  But I'm not detecting a lot of
enthusiasm for doing the work.

            regards, tom lane

On Sun, Aug 10, 2025 at 11:48 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> "David G. Johnston" <david.g.johnston@gmail.com> writes:
> > On Sunday, August 10, 2025, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> >> Possibly we should reword the tutorial intro a bit, to the effect
> >> that you can follow along with the examples if you have a source
> >> tree at hand.  (Sadly, that's not going to be very many novices
> >> these days.)
>
> > I’d rather remove it from the docs and make a home for it in the wiki or,
> > probably better, have a separate git repository that they could clone.
>
> Making it buildable standalone would be a significant investment
> of effort I fear.  Right now it's dependent on the autoconf/makefile
> infrastructure of the surrounding Postgres source tree.
>
> The other problem would be keeping it in sync with the tutorial
> docs proper.  I guess we could pull those out of the main
> documentation altogether, and make "the Postgres tutorial" into
> a fully standalone project.  But I'm not detecting a lot of
> enthusiasm for doing the work.
>

Would it be easier enough to modify the existing bits to generate a
postgres tutorial extension that was distributed like the other
contrib modules in core? This would also give existing packagers a
simple way to make this available (or not) on their systems. Thoughts?


Robert Treat
https://xzilla.net

Robert Treat <rob@xzilla.net> writes:
> Would it be easier enough to modify the existing bits to generate a
> postgres tutorial extension that was distributed like the other
> contrib modules in core? This would also give existing packagers a
> simple way to make this available (or not) on their systems. Thoughts?

Hmm, interesting idea.  Making it fit into the contrib infrastructure
would certainly go a long way towards getting packagers to package it.

            regards, tom lane