Skip to content

Commit a37b001

Browse files
peterepetere
committed
Add init[db] option to pg_ctl
pg_ctl gets a new mode that runs initdb. Adjust the documentation a bit to not assume that initdb is the only way to run database cluster initialization. But don't replace initdb as the canonical way. Author: Zdenek Kotala <Zdenek.Kotala@Sun.COM>
1 parent da07641 commit a37b001

File tree

7 files changed

+149
-60
lines changed

7 files changed

+149
-60
lines changed

‎doc/src/sgml/config.sgml

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.235 2009/11/28 23:38:06 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.236 2009/12/10 06:32:27 petere Exp $ -->
22

33
<chapter Id="runtime-config">
44
<title>Server Configuration</title>
@@ -54,9 +54,9 @@
5454
<para>
5555
One way to set these parameters is to edit the file
5656
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
57-
which is normally kept in the data directory. (<application>initdb</>
58-
installs a default copy there.) An example of what this file might look
59-
like is:
57+
which is normally kept in the data directory. (A default copy is
58+
installed there when the database cluster directory is
59+
initialized.) An example of what this file might look like is:
6060
<programlisting>
6161
# This is a comment
6262
log_connections = yes

‎doc/src/sgml/manage-ag.sgml

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.58 2009/05/06 16:15:20 tgl Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.59 2009/12/10 06:32:27 petere Exp $ -->
22

33
<chapter id="managing-databases">
44
<title>Managing Databases</title>
@@ -119,8 +119,8 @@ CREATE DATABASE <replaceable>name</>;
119119
<para>
120120
A second database,
121121
<literal>template1</literal>,<indexterm><primary>template1</></>
122-
is also created by
123-
<command>initdb</>. Whenever a new database is created within the
122+
is also created during database cluster initialization. Whenever a
123+
new database is created within the
124124
cluster, <literal>template1</literal> is essentially cloned.
125125
This means that any changes you make in <literal>template1</> are
126126
propagated to all subsequently created databases. Therefore it is
@@ -196,7 +196,8 @@ createdb -O <replaceable>rolename</> <replaceable>dbname</>
196196
<literal>template1</>, that is, only the standard objects
197197
predefined by your version of
198198
<productname>PostgreSQL</productname>. <literal>template0</>
199-
should never be changed after <command>initdb</>. By instructing
199+
should never be changed after the database cluster has been
200+
initialized. By instructing
200201
<command>CREATE DATABASE</> to copy <literal>template0</> instead
201202
of <literal>template1</>, you can create a <quote>virgin</> user
202203
database that contains none of the site-local additions in
@@ -453,7 +454,8 @@ CREATE TABLE foo(i int);
453454
</para>
454455

455456
<para>
456-
Two tablespaces are automatically created by <literal>initdb</>. The
457+
Two tablespaces are automatically created when the database cluster
458+
is initialized. The
457459
<literal>pg_global</> tablespace is used for shared system catalogs. The
458460
<literal>pg_default</> tablespace is the default tablespace of the
459461
<literal>template1</> and <literal>template0</> databases (and, therefore,

‎doc/src/sgml/ref/initdb.sgml

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.44 2008/09/23 09:20:34 heikki Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.45 2009/12/10 06:32:28 petere Exp $
33
PostgreSQL documentation
44
-->
55

@@ -309,10 +309,20 @@ PostgreSQL documentation
309309

310310
</refsect1>
311311

312+
<refsect1>
313+
<title>Notes</title>
314+
315+
<para>
316+
<command>initdb</command> can also be invoked via
317+
<command>pg_ctl initdb</command>.
318+
</para>
319+
</refsect1>
320+
312321
<refsect1>
313322
<title>See Also</title>
314323

315324
<simplelist type="inline">
325+
<member><xref linkend="app-pg-ctl"></member>
316326
<member><xref linkend="app-postgres"></member>
317327
</simplelist>
318328
</refsect1>

‎doc/src/sgml/ref/pg_ctl-ref.sgml

Lines changed: 30 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.46 2008/06/26 01:12:19 momjian Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.47 2009/12/10 06:32:28 petere Exp $
33
PostgreSQL documentation
44
-->
55

@@ -12,7 +12,7 @@ PostgreSQL documentation
1212

1313
<refnamediv>
1414
<refname>pg_ctl</refname>
15-
<refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
15+
<refpurpose>initialize, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
1616
</refnamediv>
1717

1818
<indexterm zone="app-pg-ctl">
@@ -22,6 +22,13 @@ PostgreSQL documentation
2222
<refsynopsisdiv>
2323
<cmdsynopsis>
2424

25+
<command>pg_ctl</command>
26+
<arg choice="plain">init[db]</arg>
27+
<arg>-s</arg>
28+
<arg>-D <replaceable>datadir</replaceable></arg>
29+
<arg>-o <replaceable>options</replaceable></arg>
30+
<sbr>
31+
2532
<command>pg_ctl</command>
2633
<arg choice="plain">start</arg>
2734
<arg>-w</arg>
@@ -105,7 +112,8 @@ PostgreSQL documentation
105112
<refsect1 id="app-pg-ctl-description">
106113
<title>Description</title>
107114
<para>
108-
<application>pg_ctl</application> is a utility for starting,
115+
<application>pg_ctl</application> is a utility for initializing a
116+
<productname>PostgreSQL</productname> database cluster, starting,
109117
stopping, or restarting the <productname>PostgreSQL</productname>
110118
backend server (<xref linkend="app-postgres">), or displaying the
111119
status of a running server. Although the server can be started
@@ -115,6 +123,15 @@ PostgreSQL documentation
115123
controlled shutdown.
116124
</para>
117125

126+
<para>
127+
The <option>init</option> or <option>initdb</option> mode creates a
128+
new
129+
<productname>PostgreSQL</productname> database cluster. A database
130+
cluster is a collection of databases that are managed by a single
131+
server instance. This mode invokes the <command>initdb</command>
132+
command. See <xref linkend="app-initdb"> for details.
133+
</para>
134+
118135
<para>
119136
In <option>start</option> mode, a new server is launched. The
120137
server is started in the background, and standard input is attached to
@@ -263,6 +280,12 @@ PostgreSQL documentation
263280
option unless you are doing something unusual and get errors
264281
that the <filename>postgres</filename> executable was not found.
265282
</para>
283+
284+
<para>
285+
In <literal>init</literal> mode, this option analogously
286+
specifies the location of the <filename>initdb</filename>
287+
executable.
288+
</para>
266289
</listitem>
267290
</varlistentry>
268291

@@ -542,9 +565,10 @@ Command line was:
542565
<refsect1>
543566
<title>See Also</title>
544567

545-
<para>
546-
<xref linkend="app-postgres">
547-
</para>
568+
<simplelist type="inline">
569+
<member><xref linkend="app-initdb"></member>
570+
<member><xref linkend="app-postgres"></member>
571+
</simplelist>
548572
</refsect1>
549573

550574
</refentry>

‎doc/src/sgml/runtime.sgml

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.428 2009/04/27 16:27:36 momjian Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.429 2009/12/10 06:32:28 petere Exp $ -->
22

33
<chapter Id="runtime">
44
<title>Server Setup and Operation</title>
@@ -93,6 +93,20 @@
9393
</para>
9494
</tip>
9595

96+
<para>
97+
Alternatively, you can run <command>initdb</command> via
98+
the <xref linkend="app-pg-ctl">
99+
program<indexterm><primary>pg_ctl</></> like so:
100+
<screen>
101+
<prompt>$</> <userinput>pg_ctl -D /usr/local/pgsql/data initdb</userinput>
102+
</screen>
103+
This may be more intuitive if you are
104+
using <command>pg_ctl</command> for starting and stopping the
105+
server (see <xref linkend="server-start">), so
106+
that <command>pg_ctl</command> would be the sole command you use
107+
for managing the database server instance.
108+
</para>
109+
96110
<para>
97111
<command>initdb</command> will attempt to create the directory you
98112
specify if it does not already exist. It is likely that it will not

‎doc/src/sgml/xfunc.sgml

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.142 2009/11/30 15:49:35 petere Exp $ -->
1+
<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.143 2009/12/10 06:32:28 petere Exp $ -->
22

33
<sect1 id="xfunc">
44
<title>User-Defined Functions</title>
@@ -1353,7 +1353,8 @@ CREATE FUNCTION test(int, int) RETURNS int
13531353

13541354
<para>
13551355
Normally, all internal functions present in the
1356-
server are declared during the initialization of the database cluster (<command>initdb</command>),
1356+
server are declared during the initialization of the database cluster
1357+
(see <xref linkend="creating-cluster">),
13571358
but a user could use <command>CREATE FUNCTION</command>
13581359
to create additional alias names for an internal function.
13591360
Internal functions are declared in <command>CREATE FUNCTION</command>

0 commit comments

Comments
 (0)