pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedRe: initdb - creating clusters
8+ messages / 4 participants
[nested] [flat]
* Re: initdb - creating clusters
@ 2020-08-29 22:05 Thomas Munro <thomas.munro@gmail.com>
2020-08-31 10:09 ` Re: initdb - creating clusters Jürgen Purtz <juergen@purtz.de>
2020-09-02 13:02 ` Re: initdb - creating clusters Daniel Gustafsson <daniel@yesql.se>
0 siblings, 2 replies; 8+ messages in thread
From: Thomas Munro @ 2020-08-29 22:05 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Bruce Momjian <bruce@momjian.us>; Tom Lane <tgl@sss.pgh.pa.us>; gazzatav@gmail.com, Pg Docs <pgsql-docs@lists.postgresql.org>
On Wed, Aug 26, 2020 at 12:05 AM Daniel Gustafsson <daniel@yesql.se> wrote:
> I took the liberty of adding the proposed patch upthread to the next commitfest
> to make sure it's not forgotten about, as I do think it will improve the docs.
+ The discussions in this chapter assume that you are working with
+ an unmodified version of <productname>PostgreSQL</productname>,
+ for example one that you built from source according to the directions
+ in the preceding chapters. If you are working with a pre-packaged
Rather than "unmodified", would it be better to say something more
like "without any extra supporting infrastructure"?
My point is that packagers don't typically *modify* PG, rather they
supply a bunch of wrappers (eg Debian postgresql-common), service
management scripting (eg systemd gloopity-gloop), post-install
scripting (eg Debian's policy of automatically starting any service
when you install it, implying that it must also run initdb for you).
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: initdb - creating clusters
2020-08-29 22:05 Re: initdb - creating clusters Thomas Munro <thomas.munro@gmail.com>
@ 2020-08-31 10:09 ` Jürgen Purtz <juergen@purtz.de>
1 sibling, 0 replies; 8+ messages in thread
From: Jürgen Purtz @ 2020-08-31 10:09 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
On 30.08.20 17:21, Tom Lane wrote:
> Do you have a feeling one way or the other about whether to repeat
> some of this text in each of the relevant sub-sections? I initially
> didn't want to do that, but thinking about how people consume the
> HTML docs, I'm afraid that anything not appearing on the same page
> won't get seen.
If we do so but avoid redundant text parts, we can use the entity
mechanism or the more modern XInclude mechanism. The attached patch uses
both techniques in an example file: brin.sgml includes lorem.sgml two times.
(In both cases we should avoid files with multiple root elements, eg.
multiple <para> or <sect1> without a parent element, because this would
violate the well-formed-ness of the included XML document.)
--
J. Purtz
Attachments:
0001-lorem.patch (text/x-patch, 2.9K) download
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile
index 0401a515df..562f607190 100644
--- a/doc/src/sgml/Makefile
+++ b/doc/src/sgml/Makefile
@@ -132,8 +132,8 @@ endif
html: html-stamp
html-stamp: stylesheet.xsl postgres.sgml $(ALLSGML) $(ALL_IMAGES)
- $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
- $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
+ $(XMLLINT) $(XMLINCLUDE) --noout --xinclude --postvalid --noent $(word 2,$^)
+ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(XSLTPROC_HTML_FLAGS) $(wordlist 1,2,$^)
cp $(ALL_IMAGES) html/
cp $(srcdir)/stylesheet.css html/
touch $@
@@ -167,12 +167,12 @@ postgres.pdf:
XSLTPROC_FO_FLAGS += --stringparam img.src.path '$(srcdir)/'
%-A4.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
- $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
- $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
+ $(XMLLINT) $(XMLINCLUDE) --noout --xinclude --postvalid --noent $(word 2,$^)
+ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(XSLTPROC_FO_FLAGS) --stringparam paper.type A4 -o $@ $(wordlist 1,2,$^)
%-US.fo: stylesheet-fo.xsl %.sgml $(ALLSGML)
- $(XMLLINT) $(XMLINCLUDE) --noout --valid $(word 2,$^)
- $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) $(XSLTPROC_FO_FLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
+ $(XMLLINT) $(XMLINCLUDE) --noout --xinclude --postvalid --noent $(word 2,$^)
+ $(XSLTPROC) $(XMLINCLUDE) $(XSLTPROCFLAGS) --xinclude $(XSLTPROC_FO_FLAGS) --stringparam paper.type USletter -o $@ $(wordlist 1,2,$^)
%.pdf: %.fo $(ALL_IMAGES)
$(FOP) -fo $< -pdf $@
diff --git a/doc/src/sgml/brin.sgml b/doc/src/sgml/brin.sgml
index 4420794e5b..ac5ef96173 100644
--- a/doc/src/sgml/brin.sgml
+++ b/doc/src/sgml/brin.sgml
@@ -11,6 +11,13 @@
<sect1 id="brin-intro">
<title>Introduction</title>
+ <!-- entity mechanism -->
+ <para>via entity mechanism:</para>
+ &lorem;
+ <!-- xinclude mechanism -->
+ <para>via xinclude mechanism:</para>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="lorem.sgml" />
+
<para>
<acronym>BRIN</acronym> stands for Block Range Index.
<acronym>BRIN</acronym> is designed for handling very large tables
diff --git a/doc/src/sgml/filelist.sgml b/doc/src/sgml/filelist.sgml
index 64b5da0070..2e42197844 100644
--- a/doc/src/sgml/filelist.sgml
+++ b/doc/src/sgml/filelist.sgml
@@ -182,3 +182,5 @@
<!-- back matter -->
<!ENTITY biblio SYSTEM "biblio.sgml">
+
+<!ENTITY lorem SYSTEM "lorem.sgml">
diff --git a/doc/src/sgml/lorem.sgml b/doc/src/sgml/lorem.sgml
new file mode 100644
index 0000000000..ffb557bf22
--- /dev/null
+++ b/doc/src/sgml/lorem.sgml
@@ -0,0 +1,5 @@
+ <para>
+ Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed
+ do eiusmod tempor incididunt ut labore et dolore magna aliqua.
+ An arbitrary xref-link: <xref linkend="app-pgbasebackup"/>
+ </para>
* Re: initdb - creating clusters
2020-08-29 22:05 Re: initdb - creating clusters Thomas Munro <thomas.munro@gmail.com>
@ 2020-09-02 13:02 ` Daniel Gustafsson <daniel@yesql.se>
2020-09-02 16:43 ` Re: initdb - creating clusters Tom Lane <tgl@sss.pgh.pa.us>
1 sibling, 1 reply; 8+ messages in thread
From: Daniel Gustafsson @ 2020-09-02 13:02 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Thomas Munro <thomas.munro@gmail.com>; Bruce Momjian <bruce@momjian.us>; gazzatav@gmail.com, Pg Docs <pgsql-docs@lists.postgresql.org>
> On 30 Aug 2020, at 17:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>
> Thomas Munro <thomas.munro@gmail.com> writes:
>> + The discussions in this chapter assume that you are working with
>> + an unmodified version of <productname>PostgreSQL</productname>,
>> + for example one that you built from source according to the directions
>> + in the preceding chapters. If you are working with a pre-packaged
>
>> Rather than "unmodified", would it be better to say something more
>> like "without any extra supporting infrastructure"?
>
> So maybe "... you are working with plain
> <productname>PostgreSQL</productname> without any additional
> infrastructure, for example a copy that you built from source
> according to the directions in the preceding chapters." ?
That seems pretty clearly worded to me.
> Do you have a feeling one way or the other about whether to repeat
> some of this text in each of the relevant sub-sections? I initially
> didn't want to do that, but thinking about how people consume the
> HTML docs, I'm afraid that anything not appearing on the same page
> won't get seen.
I think you're right here, duplicating the content is probably required for it
to be useful.
cheers ./daniel
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: initdb - creating clusters
2020-08-29 22:05 Re: initdb - creating clusters Thomas Munro <thomas.munro@gmail.com>
2020-09-02 13:02 ` Re: initdb - creating clusters Daniel Gustafsson <daniel@yesql.se>
@ 2020-09-02 16:43 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-09-02 19:02 ` Re: initdb - creating clusters Daniel Gustafsson <daniel@yesql.se>
0 siblings, 1 reply; 8+ messages in thread
From: Tom Lane @ 2020-09-02 16:43 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Thomas Munro <thomas.munro@gmail.com>; Bruce Momjian <bruce@momjian.us>; gazzatav@gmail.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Daniel Gustafsson <daniel@yesql.se> writes:
> On 30 Aug 2020, at 17:21, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> Do you have a feeling one way or the other about whether to repeat
>> some of this text in each of the relevant sub-sections? I initially
>> didn't want to do that, but thinking about how people consume the
>> HTML docs, I'm afraid that anything not appearing on the same page
>> won't get seen.
> I think you're right here, duplicating the content is probably required for it
> to be useful.
I took a stab at doing it that way, as attached. (I couldn't resist
the temptation to do some minor editing on adjacent material, too.)
regards, tom lane
Attachments:
mention-package-installation-scripts-2.patch (text/x-diff, 6.5K) download
diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml
index 6cda39f3ab..f584231935 100644
--- a/doc/src/sgml/runtime.sgml
+++ b/doc/src/sgml/runtime.sgml
@@ -4,10 +4,22 @@
<title>Server Setup and Operation</title>
<para>
- This chapter discusses how to set up and run the database server
+ This chapter discusses how to set up and run the database server,
and its interactions with the operating system.
</para>
+ <para>
+ The directions in this chapter assume that you are working with
+ plain <productname>PostgreSQL</productname> without any additional
+ infrastructure, for example a copy that you built from source
+ according to the directions in the preceding chapters.
+ If you are working with a pre-packaged or vendor-supplied
+ version of <productname>PostgreSQL</productname>, it is likely that
+ the packager has made special provisions for installing and starting
+ the database server according to your system's conventions.
+ Consult the package-level documentation for details.
+ </para>
+
<sect1 id="postgres-user">
<title>The <productname>PostgreSQL</productname> User Account</title>
@@ -21,9 +33,15 @@
separate user account. This user account should only own the data
that is managed by the server, and should not be shared with other
daemons. (For example, using the user <literal>nobody</literal> is a bad
- idea.) It is not advisable to install executables owned by this
- user because compromised systems could then modify their own
- binaries.
+ idea.) In particular, it is advisable that this user account not own
+ the <productname>PostgreSQL</productname> executable files, to ensure
+ that a compromised server process could not modify those executables.
+ </para>
+
+ <para>
+ Pre-packaged versions of <productname>PostgreSQL</productname> will
+ typically create a suitable user account automatically during
+ package installation.
</para>
<para>
@@ -71,11 +89,26 @@
completely up to you where you choose to store your data. There is no
default, although locations such as
<filename>/usr/local/pgsql/data</filename> or
- <filename>/var/lib/pgsql/data</filename> are popular. To initialize a
- database cluster, use the command <xref
- linkend="app-initdb"/>,<indexterm><primary>initdb</primary></indexterm> which is
- installed with <productname>PostgreSQL</productname>. The desired
- file system location of your database cluster is indicated by the
+ <filename>/var/lib/pgsql/data</filename> are popular.
+ The data directory must be initialized before being used, using the program
+ <xref linkend="app-initdb"/><indexterm><primary>initdb</primary></indexterm>
+ which is installed with <productname>PostgreSQL</productname>.
+ </para>
+
+ <para>
+ If you are using a pre-packaged version
+ of <productname>PostgreSQL</productname>, it may well have a specific
+ convention for where to place the data directory, and it may also
+ provide a script for creating the data directory. In that case you
+ should use that script in preference to
+ running <command>initdb</command> directly.
+ Consult the package-level documentation for details.
+ </para>
+
+ <para>
+ To initialize a database cluster manually,
+ run <command>initdb</command> and specify the desired
+ file system location of the database cluster with the
<option>-D</option> option, for example:
<screen>
<prompt>$</prompt> <userinput>initdb -D /usr/local/pgsql/data</userinput>
@@ -309,10 +342,22 @@ postgres$ <userinput>initdb -D /usr/local/pgsql/data</userinput>
Before anyone can access the database, you must start the database
server. The database server program is called
<command>postgres</command>.<indexterm><primary>postgres</primary></indexterm>
- The <command>postgres</command> program must know where to
- find the data it is supposed to use. This is done with the
- <option>-D</option> option. Thus, the simplest way to start the
- server is:
+ </para>
+
+ <para>
+ If you are using a pre-packaged version
+ of <productname>PostgreSQL</productname>, it almost certainly includes
+ provisions for running the server as a background task according to the
+ conventions of your operating system. Using the package's
+ infrastructure to start the server will be much less work than figuring
+ out how to do this yourself. Consult the package-level documentation
+ for details.
+ </para>
+
+ <para>
+ The bare-bones way to start the server manually is just to invoke
+ <command>postgres</command> directly, specifying the location of the
+ data directory with the <option>-D</option> option, for example:
<screen>
$ <userinput>postgres -D /usr/local/pgsql/data</userinput>
</screen>
@@ -364,7 +409,7 @@ pg_ctl start -l logfile
<secondary>starting the server during</secondary>
</indexterm>
Autostart scripts are operating-system-specific.
- There are a few distributed with
+ There are a few example scripts distributed with
<productname>PostgreSQL</productname> in the
<filename>contrib/start-scripts</filename> directory. Installing one will require
root privileges.
@@ -1481,9 +1526,23 @@ $ <userinput>cat /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages</userinp
</indexterm>
<para>
- There are several ways to shut down the database server. You control
- the type of shutdown by sending different signals to the supervisor
+ There are several ways to shut down the database server.
+ Under the hood, they all reduce to sending a signal to the supervisor
<command>postgres</command> process.
+ </para>
+
+ <para>
+ If you are using a pre-packaged version
+ of <productname>PostgreSQL</productname>, and you used its provisions
+ for starting the server, then you should also use its provisions for
+ stopping the server. Consult the package-level documentation for
+ details.
+ </para>
+
+ <para>
+ When managing the server directly, you can control the type of shutdown
+ by sending different signals to the <command>postgres</command>
+ process:
<variablelist>
<varlistentry>
@@ -1620,6 +1679,10 @@ $ <userinput>kill -INT `head -1 /usr/local/pgsql/data/postmaster.pid`</userinput
is to dump and reload the database, though this can be slow. A
faster method is <xref linkend="pgupgrade"/>. Replication methods are
also available, as discussed below.
+ (If you are using a pre-packaged version
+ of <productname>PostgreSQL</productname>, it may provide scripts to
+ assist with major version upgrades. Consult the package-level
+ documentation for details.)
</para>
<para>
* Re: initdb - creating clusters
2020-08-29 22:05 Re: initdb - creating clusters Thomas Munro <thomas.munro@gmail.com>
2020-09-02 13:02 ` Re: initdb - creating clusters Daniel Gustafsson <daniel@yesql.se>
2020-09-02 16:43 ` Re: initdb - creating clusters Tom Lane <tgl@sss.pgh.pa.us>
@ 2020-09-02 19:02 ` Daniel Gustafsson <daniel@yesql.se>
2020-09-03 15:46 ` Re: initdb - creating clusters Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 8+ messages in thread
From: Daniel Gustafsson @ 2020-09-02 19:02 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: Thomas Munro <thomas.munro@gmail.com>; Bruce Momjian <bruce@momjian.us>; gazzatav@gmail.com, Pg Docs <pgsql-docs@lists.postgresql.org>
> On 2 Sep 2020, at 18:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> I took a stab at doing it that way, as attached. (I couldn't resist
> the temptation to do some minor editing on adjacent material, too.)
LGTM. I didn't try to build the docs with this applied, but reading it I can't
see anything odd about the markup.
cheers ./daniel
^ permalink raw reply [nested|flat] 8+ messages in thread
* Re: initdb - creating clusters
2020-08-29 22:05 Re: initdb - creating clusters Thomas Munro <thomas.munro@gmail.com>
2020-09-02 13:02 ` Re: initdb - creating clusters Daniel Gustafsson <daniel@yesql.se>
2020-09-02 16:43 ` Re: initdb - creating clusters Tom Lane <tgl@sss.pgh.pa.us>
2020-09-02 19:02 ` Re: initdb - creating clusters Daniel Gustafsson <daniel@yesql.se>
@ 2020-09-03 15:46 ` Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 8+ messages in thread
From: Tom Lane @ 2020-09-03 15:46 UTC (permalink / raw)
To: Daniel Gustafsson <daniel@yesql.se>; +Cc: Thomas Munro <thomas.munro@gmail.com>; Bruce Momjian <bruce@momjian.us>; gazzatav@gmail.com, Pg Docs <pgsql-docs@lists.postgresql.org>
Daniel Gustafsson <daniel@yesql.se> writes:
>> On 2 Sep 2020, at 18:43, Tom Lane <tgl@sss.pgh.pa.us> wrote:
>> I took a stab at doing it that way, as attached. (I couldn't resist
>> the temptation to do some minor editing on adjacent material, too.)
> LGTM. I didn't try to build the docs with this applied, but reading it I can't
> see anything odd about the markup.
Hearing no other comments, pushed.
regards, tom lane
^ permalink raw reply [nested|flat] 8+ messages in thread
end of thread, other threads:[~2020-09-03 15:46 UTC | newest]
Thread overview: 8+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2020-08-29 22:05 Re: initdb - creating clusters Thomas Munro <thomas.munro@gmail.com>
2020-08-31 10:09 ` Jürgen Purtz <juergen@purtz.de>
2020-09-02 13:02 ` Daniel Gustafsson <daniel@yesql.se>
2020-09-02 16:43 ` Tom Lane <tgl@sss.pgh.pa.us>
2020-09-02 19:02 ` Daniel Gustafsson <daniel@yesql.se>
2020-09-03 15:46 ` Tom Lane <tgl@sss.pgh.pa.us>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox