Re: BUG #14814: Documentation errors for OpenBSD

Hi Paul,

(I'm keeping the post posting).
Thanks for your message. I agree with Tom. The PostgreSQL's documentation must stay "generic".
The PostgreSQL's package on OpenBSD already have a README file with all the OpenBSD specific instructions.
You can find it in /usr/local/share/doc/pkg-readmes (or online version here:
https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/databases/postgresql/pkg/README-server?rev=1.23&content-type=text/x-cvsweb-markup )

Feel free to ask me directly if you have any questions.

Regards,

On Wed, Sep 13, 2017 at 02:00:33PM -0500, Paul Covello wrote:
> Thanks for the response, Tom. I am cc’ing the OpenBSD port maintainer here just for visibility.
>
> Port maintainer:
>
> I am not a developer or even a DBA. I am just an end user learning to set up PostGresql on OpenBSD 6.1. After installing the package using pkg_add, I began to delve into the documentation at postgresql.org.
>
> I got to this section on starting the server:
>
> https://www.postgresql.org/docs/9.6/static/server-start.html
>
>
> The documentation did not match my experience (postgresql did not start) which prompted me to file a postgresql bug report #14814 on the documentation.
>
> Specifically, the instructions on what to put in rc.local for openbsd in the documentation says this:
>
> if [ -x /usr/local/pgsql/bin/pg_ctl -a -x /usr/local/pgsql/bin/postgres ]; then
> su -l postgres -c '/usr/local/pgsql/bin/pg_ctl start -s -l /var/postgresql/log -D /usr/local/pgsql/data'
> echo -n ' postgresql'
> fi
>
> However, after taking the time to troubleshoot: This is what winds up working:
>
> if [ -x /usr/local/bin/pg_ctl -a -x /usr/local/bin/postgres ]; then
> su -l _postgresql -c '/usr/local/bin/pg_ctl start -s -l /var/postgresql/logfile -D /var/postgresql/data'
> echo -n ' postgresql'
> fi
>
> Knowing that it is openbsd policy to have service names begin with an _ (underscore) and believing that the path listed to the executable does not seem to match the hier man page on openbsd, I thought this might be a documentation bug.
>
> I want to save other users the time I spent figuring this out which is what brought me here. In Tom’s response to me below, he believes this to be a port issue.
>
> Thanks for looking into this!
>
> — Paul.
>
> > On Sep 13, 2017, at 8:54 AM, Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:
> >
> > pfcovello(at)gmail(dot)com writes:
> >> In section 18.3. Starting the Database Server there are instructions for
> >> starting the server on OpenBSD:
> >> ...
> >> However, there are several problems with this instruction.
> >
> > You seem to want us to adjust the community documentation to match
> > someone's packaging of Postgres. We can't really track every random
> > decision that packagers make; and if we tried, then the documentation
> > would be inaccurate for installations built directly from source.
> >
> > Really, best practice for a packager who is modifying the default
> > configuration like this is to also modify the copy of the documentation
> > they ship, or at least make it very plain in a README file how their
> > installation differs from the out-of-the-box defaults.
> >
> > In short, I think you've got a complaint for your packager here,
> > not one for the PG community.
> >
> > regards, tom lane
>