Updating the intro for packages - improve usability, reduce new user confusion
От | Craig Ringer |
---|---|
Тема | Updating the intro for packages - improve usability, reduce new user confusion |
Дата | |
Msg-id | CAMsr+YG8vtnqtiK-6uLkP9cEmRviUWKWS_RJ_LqTMwf8tWY-Kw@mail.gmail.com обсуждение исходный текст |
Ответы |
Re: Updating the intro for packages - improve usability, reduce newuser confusion
(Dmitry Igrishin <dmitigr@gmail.com>)
Re: Updating the intro for packages - improve usability, reduce new user confusion (Pavlo Golub <pavlo.golub@cybertec.at>) |
Список | pgsql-docs |
TL;DR: It's time to update the docs to make package-based and installer-based PostgreSQL the assumed environment our users are working with. Or at least put it on an equal footing as a first-class citizen, not relegate it to the dark corners of notes and appendices. The same is true for client drivers. I'll put my hand up to start the work, with a gradual series of small incremental patches, but only if I can get broad agreement here that it's the right thing to do first. Otherwise it's just wasting time. Why? I see a lot of confusion on Stack Overflow, chat groups, forums etc that all stems from a common cause: The PostgreSQL manual, including the intro/tutorial, is written with the assumption you installed from source and are using pg_ctl, etc directly. Very few of our users do this. The reality is that most users are immediately faced with: psql: FATAL: role "myname" does not exist as their first PostgreSQL experience, or psql: could not connect to server: No such file or directory Is the server running locally and accepting connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"? I think it's time to admit that most users first experience PostgreSQL via packages or installers, and moreover that we should encourage that. Joe "Never Used Linux Before" Bloggs and Julie "Is Terminal where I put the commands?" Smith should not be dealing with configure, make, macports, etc. We shouldn't leave them in the dark to figure out they want "systemctl enable --now postgresql-11.service" and that they need to "/usr/pgsql-10/bin/postgresql-10-setup" first. Or are they on Debian? Oh, then they need `pg_ctlcluster`, and the cluster is autocreated. We let the poor confused user sort this mess out. We, PGDG, ship these packages. We shouldn't entirely ignore them in our own documentation. That sucks for users. PostgreSQL has a reputation as a great DBMS that's hard to get started with. That reputation is deserved. Some trivial changes can ease that learning curve a lot. So of course we get people installing Pg from packages, then initdb'ing and pg_ctl'ing their own clusters instead of using pg_createcluster or working with systemctl. Sigh. Then they complain that postgres "crashed" when they restarted, because of course they didn't integrate it with their init system. How would they? We didn't tell them how, or that they had to. It's such a mess and I have better things to do than deal with these unnecessary horrors when I work with clients on real problems. Look at what some popular systems do. Slick docs that get any idiot straight to running the system, even if perhaps they shouldn't. I don't want to go that far, with the sort of curl https://get.postgresql.org/11 | sudo bash horror that I see many places. But we can do better than we do now without encouraging hideously insecure and unmaintainable deployments. (It's bad enough that we nearly totally ignore the client drivers everyone actually uses - come on, how many of you write direct libpq code on a day to day basis? Good luck finding PgJDBC, nPgSQL, psycopg2, DBD::Pg or the Pg gem in our manual; hell, they most don't even appear to be mentioned in the SOURCE TREE anywhere. psqlODBC is mentioned - once - in "external projects".). So I propose to restructure our intro docs to emphasise common package based deployments, with a focus on the entrypoints at: * https://www.postgresql.org/docs/current/tutorial-start.html * https://www.postgresql.org/docs/current/tutorial-install.html * https://www.postgresql.org/docs/current/installation.html I realise we cannot cover everything, but we should: * Move "installation from source code" from "installation.html" to a subhead * Instead have the "installation" page list: - Installation from Packages on Linux - Fedora, RHEL, CentOS (mention PGDG and distro packages) - Debian and Ubuntu (mention PGDG and distro packages) - Other options (-> www.postgresql.org download page) - Installation with an installer program - (-> download page) - Installation from Ports on *BSD - Installation from source distribution - git clone (lets face it, if you use source you use git now) - tarball Keep a section of the manual dedicated to common distribution and install methods, where we can collect and maintain this info so it's not scattered. Cross-reference it from elsewhere. So for example under https://www.postgresql.org/docs/current/server-start.html we'd xref the distro/OS specific part, and one of those dist/OS specific parts would cover source installs. Right now when you read the docs, it's all about the source install, with distro/packaged stuff a half-considered afterthought mentioned after the manual stuff. A user should be able to easily open the "Fedora/RHEL/CentOS" section to get taken to the "Starting PostgreSQL on RHEL, CentOS or Fedora" section of the distro-specific info in the manual. With, of course, a note there saying that this applies if you installed from packages, and xrefs for manual source installs and installer-binary installs. We should have prominent links in the tutorial install section that link to: * Linux: apt.postgresql.org and yum.postgresql.org * the postgresql download page * https://help.ubuntu.com/community/PostgreSQL for package-related info on the Debian and Ubuntu variants * https://fedoraproject.org/wiki/PostgreSQL for Fedora/RHEL/CentOS package-related info These are long lived, stable, well known links, and we're long past the days where someone's reading the docs on a printout. Hell, most people don't even realise we have docs packages rather than just the website! We should also have a short, simple "concepts" section in the tutorial (or tweak the architecture fundamentals section) that explains a few key points of frequent confusion: * Explicitly mention that on most package installs you use `sudo -u postgres psql` to get a "postgres" superuser shell. Give the Mac and Windows equivalents too. * Explain that PostgreSQL is a client/server system. The psql client connects to a server, either on the same computer or elsewhere via a network. The server is "postgres", the usual client is "psql" but there are others. * Explain that whenever we write "postgres=#" we mean "run this as a postgres superuser" * The "psql" shell is a separate program to the "sh" or "bash" shell. It takes SQL commands and special backslash-commands. You cannot run SQL on the system shell, and you cannot run system commands on the psql shell. * There are GUIs like PgAdmin4, OmniDB, HeidiSQL, DBeaver, etc that some people will prefer. These tools may NOT support the psql backslash commands the user manual describes. The manual is written with the assumption that you use psql. In particular \COPY will NOT work on many of them. * The "createuser", "createdb" etc commands are command-line ("Command Prompt", Terminal, etc) commands, NOT psql commands. They have sql equivalents like CREATE USER, CREATE DATABASE, etc. * Give a simple recipe for how to make your own user account with your own db and set up peer auth for it, so you can get started simply, like sudo -u postgres psql -c "CREATE USER ${USER} WITH CREATEDB CREATEROLE; CREATE DATABASE $user WITH OWNER ${USER};" It's a shame we don't have an ALTER SYSTEM equivalent for pg_hba.conf, but most packages ship with 'peer' enabled, so it should Just Work. Anyway. I know that was long, but I wanted to actually explain WHAT I want to change in the docs and HOW, not just "lets change some stuff ok?". I'll have extremely limited time to do this, but I hope to deliver a stream of small and simple patches to do it piece-by-piece. -- Craig Ringer http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Training & Services
В списке pgsql-docs по дате отправления: