Greg,
thanks for your useful comments. I attached new doc patch version. I
removed example changes and add link to create database cluster (I hope)
everywhere. Please, look on it and let me know if there is still
something what should be changed.
Thanks Zdenek
Greg Smith píše v ne 06. 12. 2009 v 22:29 -0500:
> I just noticed that there was an updated patch here that never made its
> way onto the CommitFest app listing. I just fixed that and took a quick
> look at it. I was in favor of this code change, but I have to say even
> I don't really like how it ended up getting documented--and I'm sure
> there are others would be downright hostile toward it.
>
> The biggest problem is that all of the places that used to say
> "<command><initdb>" when talking about creating a cluster now just say
> "database cluster initialization"--with no link to a section covering
> that topic. That's not a good forward step. The part I'm more
> favorable toward that I expect other people to really cringe at is that
> the examples showing how to manually run initdb have all been switched
> to use "pg_ctl initdb" too.
>
> If we're going to have a smooth transition toward supporting both styles
> of working in the next release, I think what needs to happen to the
> documentation here is adding a very clear section saying that "initdb"
> and "pg_ctl initdb" are the same thing, and noting why both forms
> exist. Maybe a short note in both pg_ctl and initdb pointing at each
> other; not sure yet what's best. Then update all the current places
> that say "initdb" that have been rewritten in this doc patch to
> "database cluster initialization" to reference things appropriate still.
>
> Going as far as making all the examples exclusively use the pg_ctl form
> right now is probably more than the community at large wants to handle
> just yet I suspect. At best, maybe we could make some or all of those
> either use both forms, or link them to the new discussion of
> alternatives section.
>
> I'm glad we made some progress (and are basically at code complete now)
> on this patch this round. Given that this patch doesn't have a large
> amount of support, I think that the remaining work here is fine-tuning
> the documentation to cover the new option available without introducing
> and abrupt change people won't like. I'm going to mark this "returned
> with feedback" for now since I think that's going to take a bit more
> work than we really have time for right now, particularly given the
> limited number of people who care about this change. Zdenek, once this
> CommitFest clears out, I can help out with getting the documentation
> parts here smoothed over so this is in proper shape to commit during the
> next one; I don't think there's anything left you need to do.
>
diff -r ab32ed8164e7 doc/src/sgml/config.sgml
--- a/doc/src/sgml/config.sgml Mon Dec 07 15:10:09 2009 +0100
+++ b/doc/src/sgml/config.sgml Mon Dec 07 17:12:32 2009 +0100
@@ -54,9 +54,10 @@
<para>
One way to set these parameters is to edit the file
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
- which is normally kept in the data directory. (<application>initdb</>
- installs a default copy there.) An example of what this file might look
- like is:
+ which is normally kept in the data directory.
+ (<link linkend="creating-cluster">database cluster initialization</link>
+ process installs a default copy there.)
+ An example of what this file might look like is:
<programlisting>
# This is a comment
log_connections = yes
@@ -365,8 +366,8 @@
Determines the maximum number of concurrent connections to the
database server. The default is typically 100 connections, but
might be less if your kernel settings will not support it (as
- determined during <application>initdb</>). This parameter can
- only be set at server start.
+ determined during <link linkend="creating-cluster">database cluster
+ initialization</link>). This parameter can only be set at server start.
</para>
<para>
@@ -747,7 +748,8 @@
Sets the amount of memory the database server uses for shared
memory buffers. The default is typically 32 megabytes
(<literal>32MB</>), but might be less if your kernel settings will
- not support it (as determined during <application>initdb</>).
+ not support it (as determined during <link linkend="creating-cluster">database
+ cluster initialization)</link>.
This setting must be at least 128 kilobytes. (Non-default
values of <symbol>BLCKSZ</symbol> change the minimum.) However,
settings significantly higher than the minimum are usually needed
@@ -4267,10 +4269,10 @@
keywords <literal>US</>, <literal>NonEuro</>, and
<literal>NonEuropean</> are synonyms for <literal>MDY</>. See
<xref linkend="datatype-datetime"> for more information. The
- built-in default is <literal>ISO, MDY</>, but
- <application>initdb</application> will initialize the
- configuration file with a setting that corresponds to the
- behavior of the chosen <varname>lc_time</varname> locale.
+ built-in default is <literal>ISO, MDY</>, but
+ <link linkend="creating-cluster">database cluster initialization</link>
+ will initialize the configuration file with a setting that corresponds
+ to the behavior of the chosen <varname>lc_time</varname> locale.
</para>
</listitem>
</varlistentry>
@@ -4476,9 +4478,9 @@
specifying the configuration.
See <xref linkend="textsearch"> for further information.
The built-in default is <literal>pg_catalog.simple</>, but
- <application>initdb</application> will initialize the
- configuration file with a setting that corresponds to the
- chosen <varname>lc_ctype</varname> locale, if a configuration
+ <link linkend="creating-cluster">database cluster initialization</link>
+ will initialize the configuration file with a setting that corresponds
+ to the chosen <varname>lc_ctype</varname> locale, if a configuration
matching that locale can be identified.
</para>
</listitem>
@@ -5240,8 +5242,9 @@
<listitem>
<para>
Allows modification of the structure of system tables.
- This is used by <command>initdb</command>.
- This parameter can only be set at server start.
+ This is used by <link linkend="creating-cluster">database cluster
+ initialization</link> process. This parameter can only be set at server
+ start.
</para>
</listitem>
</varlistentry>
diff -r ab32ed8164e7 doc/src/sgml/manage-ag.sgml
--- a/doc/src/sgml/manage-ag.sgml Mon Dec 07 15:10:09 2009 +0100
+++ b/doc/src/sgml/manage-ag.sgml Mon Dec 07 17:12:32 2009 +0100
@@ -107,10 +107,9 @@
Since you need to be connected to the database server in order to
execute the <command>CREATE DATABASE</command> command, the
question remains how the <emphasis>first</> database at any given
- site can be created. The first database is always created by the
- <command>initdb</> command when the data storage area is
- initialized. (See <xref linkend="creating-cluster">.) This
- database is called
+ site can be created. The first database is always created when
+ the data storage area is initialized. (See <xref linkend="creating-cluster">.)
+ This database is called
<literal>postgres</>.<indexterm><primary>postgres</></> So to
create the first <quote>ordinary</> database you can connect to
<literal>postgres</>.
@@ -119,8 +118,8 @@
<para>
A second database,
<literal>template1</literal>,<indexterm><primary>template1</></>
- is also created by
- <command>initdb</>. Whenever a new database is created within the
+ is also created during <link linkend="creating-cluster">database cluster
+ initialization</link>. Whenever a new database is created within the
cluster, <literal>template1</literal> is essentially cloned.
This means that any changes you make in <literal>template1</> are
propagated to all subsequently created databases. Therefore it is
@@ -196,11 +195,11 @@
<literal>template1</>, that is, only the standard objects
predefined by your version of
<productname>PostgreSQL</productname>. <literal>template0</>
- should never be changed after <command>initdb</>. By instructing
- <command>CREATE DATABASE</> to copy <literal>template0</> instead
- of <literal>template1</>, you can create a <quote>virgin</> user
- database that contains none of the site-local additions in
- <literal>template1</>. This is particularly handy when restoring a
+ should never be changed after <link linkend="creating-cluster">database cluster
+ initialization</link>. By instructing <command>CREATE DATABASE</> to copy
+ <literal>template0</> instead of <literal>template1</>, you can create a
+ <quote>virgin</> user database that contains none of the site-local additions
+ in <literal>template1</>. This is particularly handy when restoring a
<literal>pg_dump</> dump: the dump script should be restored in a
virgin database to ensure that one recreates the correct contents
of the dumped database, without any conflicts with objects that
@@ -453,8 +452,9 @@
</para>
<para>
- Two tablespaces are automatically created by <literal>initdb</>. The
- <literal>pg_global</> tablespace is used for shared system catalogs. The
+ Two tablespaces are automatically created during
+ <link linkend="creating-cluster">database cluster initialization</link>.
+ The <literal>pg_global</> tablespace is used for shared system catalogs. The
<literal>pg_default</> tablespace is the default tablespace of the
<literal>template1</> and <literal>template0</> databases (and, therefore,
will be the default tablespace for other databases as well, unless
diff -r ab32ed8164e7 doc/src/sgml/ref/initdb.sgml
--- a/doc/src/sgml/ref/initdb.sgml Mon Dec 07 15:10:09 2009 +0100
+++ b/doc/src/sgml/ref/initdb.sgml Mon Dec 07 17:12:32 2009 +0100
@@ -106,6 +106,12 @@
More details can be found in <xref linkend="multibyte">.
</para>
+ <para>
+ Note: The <command>initdb</command> might be invoked by
+ <command>pg_ctl initdb</command> and <command>initdb</command> cannot be in
+ default path on a <productname>PostgreSQL</productname> installations.
+ </para>
+
</refsect1>
<refsect1>
@@ -314,6 +320,7 @@
<simplelist type="inline">
<member><xref linkend="app-postgres"></member>
+ <member><xref linkend="app-pg-ctl"></member>
</simplelist>
</refsect1>
diff -r ab32ed8164e7 doc/src/sgml/ref/pg_ctl-ref.sgml
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml Mon Dec 07 15:10:09 2009 +0100
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml Mon Dec 07 17:12:32 2009 +0100
@@ -12,7 +12,7 @@
<refnamediv>
<refname>pg_ctl</refname>
- <refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
+ <refpurpose>init, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
</refnamediv>
<indexterm zone="app-pg-ctl">
@@ -23,6 +23,13 @@
<cmdsynopsis>
<command>pg_ctl</command>
+ <arg choice="plain">init[db]</arg>
+ <arg>-D <replaceable>datadir</replaceable></arg>
+ <arg>-s</arg>
+ <arg>-o <replaceable>options</replaceable></arg>
+ <sbr>
+
+ <command>pg_ctl</command>
<arg choice="plain">start</arg>
<arg>-w</arg>
<arg>-t <replaceable>seconds</replaceable></arg>
@@ -105,7 +112,8 @@
<refsect1 id="app-pg-ctl-description">
<title>Description</title>
<para>
- <application>pg_ctl</application> is a utility for starting,
+ <application>pg_ctl</application> is a utility for initialiazing
+ <productname>PostgreSQL</productname> database cluster, starting,
stopping, or restarting the <productname>PostgreSQL</productname>
backend server (<xref linkend="app-postgres">), or displaying the
status of a running server. Although the server can be started
@@ -116,6 +124,14 @@
</para>
<para>
+ <option>init</option> or <option>initdb</option> creates a new
+ <productname>PostgreSQL</productname> database cluster. A database
+ cluster is a collection of databases that are managed by a single
+ server instance. This options invokes <application><xref linkend="app-initdb">
+ </application> command. See <xref linkend="app-initdb"> for more details.
+ </para>
+
+ <para>
In <option>start</option> mode, a new server is launched. The
server is started in the background, and standard input is attached to
<filename>/dev/null</filename>. The standard output and standard
diff -r ab32ed8164e7 doc/src/sgml/runtime.sgml
--- a/doc/src/sgml/runtime.sgml Mon Dec 07 15:10:09 2009 +0100
+++ b/doc/src/sgml/runtime.sgml Mon Dec 07 17:12:32 2009 +0100
@@ -72,13 +72,16 @@
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</></> which is
+ database cluster, use the command <xref linkend="app-pg-ctl"> or <xref
+ linkend="app-initdb">,<indexterm><primary>initdb</></>
+ <indexterm><primary>pg_ctl</></> which is
installed with <productname>PostgreSQL</productname>. The desired
file system location of your database cluster is indicated by the
<option>-D</option> option, for example:
<screen>
<prompt>$</> <userinput>initdb -D /usr/local/pgsql/data</userinput>
+or
+<prompt>$</> <userinput>pg_ctl -D /usr/local/pgsql/data initdb</userinput>
</screen>
Note that you must execute this command while logged into the
<productname>PostgreSQL</productname> user account, which is
diff -r ab32ed8164e7 doc/src/sgml/xfunc.sgml
--- a/doc/src/sgml/xfunc.sgml Mon Dec 07 15:10:09 2009 +0100
+++ b/doc/src/sgml/xfunc.sgml Mon Dec 07 17:12:32 2009 +0100
@@ -1353,8 +1353,8 @@
<para>
Normally, all internal functions present in the
- server are declared during the initialization of the database cluster (<command>initdb</command>),
- but a user could use <command>CREATE FUNCTION</command>
+ server are declared during the <link linkend="creating-cluster">initialization
+ of the database cluster</link>, but a user could use <command>CREATE FUNCTION</command>
to create additional alias names for an internal function.
Internal functions are declared in <command>CREATE FUNCTION</command>
with language name <literal>internal</literal>. For instance, to
--
Sent via pgsql-hackers mailing list (pgsql-hackers@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-hackers
