[patch] pg_ctl init extension
Attached patch extends pg_ctl command with init option.
pg_ctl -D /var/lib/postgres [-s] init
This should replace usage of initdb command which has problematic name
as we already discussed several times. Initdb binary will be still
there, but it can be renamed and move into execlib dir in the future.
Patch does not contains documentation changes. They will depends on
decision which database initialization method will be preferred.
Zdenek
Attachments:
pg_ctl.patchtext/x-patch; CHARSET=US-ASCII; name=pg_ctl.patchDownload
*** pgsql_init.8d83e5030d44/src/bin/pg_ctl/pg_ctl.c 2009-09-17 21:42:20.865268360 +0200
--- /export/home/zk200664/work/mercurial/pgsql_init/src/bin/pg_ctl/pg_ctl.c 2009-09-17 21:15:04.630265322 +0200
***************
*** 57,62 ****
--- 57,63 ----
typedef enum
{
NO_COMMAND = 0,
+ INIT_COMMAND,
START_COMMAND,
STOP_COMMAND,
RESTART_COMMAND,
***************
*** 100,105 ****
--- 101,107 ----
static void do_help(void);
static void set_mode(char *modeopt);
static void set_sig(char *signame);
+ static void do_init(void);
static void do_start(void);
static void do_stop(void);
static void do_restart(void);
***************
*** 615,620 ****
--- 617,655 ----
}
static void
+ do_init(void)
+ {
+ char pg_initdb[MAXPGPATH];
+ char cmd[MAXPGPATH];
+ int ret;
+
+ if ((ret = find_other_exec(argv0, "initdb", "initdb (PostgreSQL) " PG_VERSION "\n",
+ pg_initdb)) < 0)
+
+ {
+ write_stderr(_("%s: could not find initdb\n"),
+ progname);
+ exit(1);
+ }
+
+ if (post_opts == NULL)
+ post_opts = "";
+
+ if (!silent_mode)
+ snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s" SYSTEMQUOTE,
+ pg_initdb, pgdata_opt, post_opts);
+ else
+ snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s > \"%s\"" SYSTEMQUOTE,
+ pg_initdb, pgdata_opt, post_opts, DEVNULL);
+
+ if ( system(cmd) != 0 )
+ {
+ write_stderr(_("%s: database initialization failed.\n"), progname);
+ exit(1);
+ }
+ }
+
+ static void
do_start(void)
{
pgpid_t pid;
***************
*** 694,700 ****
progname, exitcode);
exit(1);
}
-
if (old_pid != 0)
{
pg_usleep(1000000);
--- 729,734 ----
***************
*** 1535,1540 ****
--- 1569,1575 ----
printf(_("%s is a utility to start, stop, restart, reload configuration files,\n"
"report the status of a PostgreSQL server, or signal a PostgreSQL process.\n\n"), progname);
printf(_("Usage:\n"));
+ printf(_(" %s init [-D DATADIR] [-s] [-o \"OPTIONS\"]\n"), progname);
printf(_(" %s start [-w] [-t SECS] [-D DATADIR] [-s] [-l FILENAME] [-o \"OPTIONS\"]\n"), progname);
printf(_(" %s stop [-W] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"), progname);
printf(_(" %s restart [-w] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"
***************
*** 1567,1573 ****
#endif
printf(_(" -l, --log FILENAME write (or append) server log to FILENAME\n"));
printf(_(" -o OPTIONS command line options to pass to postgres\n"
! " (PostgreSQL server executable)\n"));
printf(_(" -p PATH-TO-POSTGRES normally not necessary\n"));
printf(_("\nOptions for stop or restart:\n"));
printf(_(" -m SHUTDOWN-MODE can be \"smart\", \"fast\", or \"immediate\"\n"));
--- 1602,1608 ----
#endif
printf(_(" -l, --log FILENAME write (or append) server log to FILENAME\n"));
printf(_(" -o OPTIONS command line options to pass to postgres\n"
! " (PostgreSQL server executable) or initdb\n"));
printf(_(" -p PATH-TO-POSTGRES normally not necessary\n"));
printf(_("\nOptions for stop or restart:\n"));
printf(_(" -m SHUTDOWN-MODE can be \"smart\", \"fast\", or \"immediate\"\n"));
***************
*** 1824,1830 ****
exit(1);
}
! if (strcmp(argv[optind], "start") == 0)
ctl_command = START_COMMAND;
else if (strcmp(argv[optind], "stop") == 0)
ctl_command = STOP_COMMAND;
--- 1859,1867 ----
exit(1);
}
! if (strcmp(argv[optind], "init") == 0)
! ctl_command = INIT_COMMAND;
! else if (strcmp(argv[optind], "start") == 0)
ctl_command = START_COMMAND;
else if (strcmp(argv[optind], "stop") == 0)
ctl_command = STOP_COMMAND;
***************
*** 1921,1926 ****
--- 1958,1966 ----
switch (ctl_command)
{
+ case INIT_COMMAND:
+ do_init();
+ break;
case STATUS_COMMAND:
do_status();
break;
On tor, 2009-09-17 at 21:43 +0200, Zdenek Kotala wrote:
Attached patch extends pg_ctl command with init option.
pg_ctl -D /var/lib/postgres [-s] init
This should replace usage of initdb command which has problematic name
as we already discussed several times. Initdb binary will be still
there, but it can be renamed and move into execlib dir in the future.
If the name is a problem, why not change the name? What you are
proposing above is effectively a very elaborate name change, so why not
go for a simpler one?
--On 17. September 2009 23:00:12 +0300 Peter Eisentraut <peter_e@gmx.net>
wrote:
f the name is a problem, why not change the name? What you are
proposing above is effectively a very elaborate name change, so why not
go for a simpler one?
I don't like the solution by using -o "<initdb options>" to push down
command line options to initdb. I always had the opinion that this was (and
is) a valid workaround for postgres itself, but it doesn't feel correct to
expose that further to initdb and its purposes.
My 2 cents...
--
Thanks
Bernd
Peter Eisentraut píše v čt 17. 09. 2009 v 23:00 +0300:
On tor, 2009-09-17 at 21:43 +0200, Zdenek Kotala wrote:
Attached patch extends pg_ctl command with init option.
pg_ctl -D /var/lib/postgres [-s] init
This should replace usage of initdb command which has problematic name
as we already discussed several times. Initdb binary will be still
there, but it can be renamed and move into execlib dir in the future.If the name is a problem, why not change the name? What you are
proposing above is effectively a very elaborate name change, so why not
go for a simpler one?
The idea is to have one command for server control. By my opinion init
logically belongs to group of command like start/stop. It is also
possible to add parameter for init+start in one command and so on.
If you look on ZFS you have only two commands to manage everything, it
is easy and you can start to use ZFS very quickly. I think this patch
increase usability/adoption od postgreSQL for newbies.
And second big advantage is that it would be possible easily extend
pg_ctl to cope with different postgresql versions (e.g. "pg_ctl -v 8.2
-D . init"). There is no reason why pg_ctl couldn't start different
postgreSQL version depends on PG_VERSION in data directory.
Zdenek
Bernd Helmle píše v čt 17. 09. 2009 v 23:26 +0200:
--On 17. September 2009 23:00:12 +0300 Peter Eisentraut <peter_e@gmx.net>
wrote:f the name is a problem, why not change the name? What you are
proposing above is effectively a very elaborate name change, so why not
go for a simpler one?I don't like the solution by using -o "<initdb options>" to push down
command line options to initdb. I always had the opinion that this was (and
is) a valid workaround for postgres itself, but it doesn't feel correct to
expose that further to initdb and its purposes.
hmm, I could modify it that all args after init keyword will be pass to
the initdb like this:
pg_ctl -D /tmp/db init [<my favorite switches>]
initdb [<my favorite switches>]
and "pg_ctl -h init" will show help which commands are allowed.
Zdenek
On tor, 2009-09-17 at 21:43 +0200, Zdenek Kotala wrote:
Attached patch extends pg_ctl command with init option.
pg_ctl -D /var/lib/postgres [-s] init
This should replace usage of initdb command which has problematic name
as we already discussed several times. Initdb binary will be still
there, but it can be renamed and move into execlib dir in the future.Patch does not contains documentation changes. They will depends on
decision which database initialization method will be preferred.
OK, let's see. The patch is pretty straightforward, but does anyone
else actually want this? Comments?
Peter Eisentraut píše v so 14. 11. 2009 v 10:41 +0200:
On tor, 2009-09-17 at 21:43 +0200, Zdenek Kotala wrote:
Attached patch extends pg_ctl command with init option.
pg_ctl -D /var/lib/postgres [-s] init
This should replace usage of initdb command which has problematic name
as we already discussed several times. Initdb binary will be still
there, but it can be renamed and move into execlib dir in the future.Patch does not contains documentation changes. They will depends on
decision which database initialization method will be preferred.OK, let's see. The patch is pretty straightforward, but does anyone
else actually want this? Comments?
Maybe we could ask on general where is more admins. I will send voting
email.
thanks for looking on this
Zdenek
Peter Eisentraut wrote:
The patch is pretty straightforward,
but does anyone else actually want this? Comments?
I agree that the initdb name seems odd next to the other executable
names, but the functionality seems a little out of place to me in
pg_ctl. The other options all correspond (more or less) to LSB init
script actions (and we've been talking about the desirability of
making that a closer fit); while this is something which would *not
be appropriate* in an init script. We could filter this option out
in the script, but it seemed like you wanted to keep the script as
short and simple as possible....
-Kevin
Import Notes
Resolved by subject fallback
"Kevin Grittner" <Kevin.Grittner@wicourts.gov> writes:
Peter Eisentraut wrote:
The patch is pretty straightforward,
but does anyone else actually want this? Comments?
I agree that the initdb name seems odd next to the other executable
names, but the functionality seems a little out of place to me in
pg_ctl. The other options all correspond (more or less) to LSB init
script actions (and we've been talking about the desirability of
making that a closer fit); while this is something which would *not
be appropriate* in an init script.
Well, it's not appropriate or safe as a default action, but there
already is a nonstandard "service postgresql init" action in at least
the PGDG and Red Hat init scripts. In fact, I believe that Zdenek's
entire rationale for this is predicated on the assumption that he can
eventually make initdb's disappearance transparent, if he can get
people used to using such a thing instead of initdb'ing by hand.
regards, tom lane
On lör, 2009-11-14 at 14:50 +0100, Zdenek Kotala wrote:
Peter Eisentraut píše v so 14. 11. 2009 v 10:41 +0200:
On tor, 2009-09-17 at 21:43 +0200, Zdenek Kotala wrote:
Attached patch extends pg_ctl command with init option.
pg_ctl -D /var/lib/postgres [-s] init
This should replace usage of initdb command which has problematic name
as we already discussed several times. Initdb binary will be still
there, but it can be renamed and move into execlib dir in the future.Patch does not contains documentation changes. They will depends on
decision which database initialization method will be preferred.OK, let's see. The patch is pretty straightforward, but does anyone
else actually want this? Comments?Maybe we could ask on general where is more admins. I will send voting
email.
I think this is over now. There was some support, some "don't care, but
could make sense", and no one violently objecting, so please finish the
patch up with documentation, and it can go in as far as I'm concerned.
Someone was proposing that pg_ctl initdb be an alias to pg_ctl init.
Perhaps you could add that.
I attached updated patch and doc patch.
Zdenek
Peter Eisentraut píše v so 21. 11. 2009 v 13:19 +0200:
Show quoted text
On lör, 2009-11-14 at 14:50 +0100, Zdenek Kotala wrote:
Peter Eisentraut píše v so 14. 11. 2009 v 10:41 +0200:
On tor, 2009-09-17 at 21:43 +0200, Zdenek Kotala wrote:
Attached patch extends pg_ctl command with init option.
pg_ctl -D /var/lib/postgres [-s] init
This should replace usage of initdb command which has problematic name
as we already discussed several times. Initdb binary will be still
there, but it can be renamed and move into execlib dir in the future.Patch does not contains documentation changes. They will depends on
decision which database initialization method will be preferred.OK, let's see. The patch is pretty straightforward, but does anyone
else actually want this? Comments?Maybe we could ask on general where is more admins. I will send voting
email.I think this is over now. There was some support, some "don't care, but
could make sense", and no one violently objecting, so please finish the
patch up with documentation, and it can go in as far as I'm concerned.Someone was proposing that pg_ctl initdb be an alias to pg_ctl init.
Perhaps you could add that.
Attachments:
pg_ctl_02.patchtext/x-patch; CHARSET=US-ASCII; name=pg_ctl_02.patchDownload
diff -r 2d87758e836b src/bin/pg_ctl/pg_ctl.c
--- a/src/bin/pg_ctl/pg_ctl.c Sun Nov 22 22:06:30 2009 +0000
+++ b/src/bin/pg_ctl/pg_ctl.c Fri Dec 04 22:13:28 2009 +0100
@@ -57,6 +57,7 @@
typedef enum
{
NO_COMMAND = 0,
+ INIT_COMMAND,
START_COMMAND,
STOP_COMMAND,
RESTART_COMMAND,
@@ -100,6 +101,7 @@
static void do_help(void);
static void set_mode(char *modeopt);
static void set_sig(char *signame);
+static void do_init(void);
static void do_start(void);
static void do_stop(void);
static void do_restart(void);
@@ -615,6 +617,38 @@
}
static void
+do_init(void)
+{
+ char pg_initdb[MAXPGPATH];
+ char cmd[MAXPGPATH];
+ int ret;
+
+ if ((ret = find_other_exec(argv0, "initdb", "initdb (PostgreSQL) " PG_VERSION "\n",
+ pg_initdb)) < 0)
+ {
+ write_stderr(_("%s: could not find initdb\n"),
+ progname);
+ exit(1);
+ }
+
+ if (post_opts == NULL)
+ post_opts = "";
+
+ if (!silent_mode)
+ snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s" SYSTEMQUOTE,
+ pg_initdb, pgdata_opt, post_opts);
+ else
+ snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s > \"%s\"" SYSTEMQUOTE,
+ pg_initdb, pgdata_opt, post_opts, DEVNULL);
+
+ if ( system(cmd) != 0 )
+ {
+ write_stderr(_("%s: database initialization failed.\n"), progname);
+ exit(1);
+ }
+}
+
+static void
do_start(void)
{
pgpid_t pid;
@@ -1536,6 +1570,7 @@
printf(_("%s is a utility to start, stop, restart, reload configuration files,\n"
"report the status of a PostgreSQL server, or signal a PostgreSQL process.\n\n"), progname);
printf(_("Usage:\n"));
+ printf(_(" %s init[db] [-D DATADIR] [-s] [-o \"OPTIONS\"]\n"), progname);
printf(_(" %s start [-w] [-t SECS] [-D DATADIR] [-s] [-l FILENAME] [-o \"OPTIONS\"]\n"), progname);
printf(_(" %s stop [-W] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"), progname);
printf(_(" %s restart [-w] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"
@@ -1568,7 +1603,7 @@
#endif
printf(_(" -l, --log FILENAME write (or append) server log to FILENAME\n"));
printf(_(" -o OPTIONS command line options to pass to postgres\n"
- " (PostgreSQL server executable)\n"));
+ " (PostgreSQL server executable) or initdb\n"));
printf(_(" -p PATH-TO-POSTGRES normally not necessary\n"));
printf(_("\nOptions for stop or restart:\n"));
printf(_(" -m SHUTDOWN-MODE can be \"smart\", \"fast\", or \"immediate\"\n"));
@@ -1825,7 +1860,11 @@
exit(1);
}
- if (strcmp(argv[optind], "start") == 0)
+ if (strcmp(argv[optind], "init") == 0)
+ ctl_command = INIT_COMMAND;
+ else if (strcmp(argv[optind], "initdb") == 0)
+ ctl_command = INIT_COMMAND;
+ else if (strcmp(argv[optind], "start") == 0)
ctl_command = START_COMMAND;
else if (strcmp(argv[optind], "stop") == 0)
ctl_command = STOP_COMMAND;
@@ -1922,6 +1961,9 @@
switch (ctl_command)
{
+ case INIT_COMMAND:
+ do_init();
+ break;
case STATUS_COMMAND:
do_status();
break;
pg_ctl_01_doc.patchtext/x-patch; CHARSET=US-ASCII; name=pg_ctl_01_doc.patchDownload
diff -r 5af127be4a67 doc/src/sgml/config.sgml
--- a/doc/src/sgml/config.sgml Mon Nov 23 09:06:21 2009 +0100
+++ b/doc/src/sgml/config.sgml Fri Dec 04 21:04:34 2009 +0100
@@ -114,8 +52,8 @@
<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
+ which is normally kept in the data directory. (database cluster initialization
+ process installs a default copy there.) An example of what this file might look
like is:
<programlisting>
# This is a comment
@@ -425,7 +363,7 @@
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
+ determined during database cluster initialization). This parameter can
only be set at server start.
</para>
@@ -807,7 +745,7 @@
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 database cluster initialization).
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
@@ -4284,7 +4222,7 @@
<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
+ database cluster initialization will initialize the
configuration file with a setting that corresponds to the
behavior of the chosen <varname>lc_time</varname> locale.
</para>
@@ -4492,7 +4430,7 @@
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
+ database cluster initialization 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.
@@ -5256,7 +5194,7 @@
<listitem>
<para>
Allows modification of the structure of system tables.
- This is used by <command>initdb</command>.
+ This is used by database cluster initialization process.
This parameter can only be set at server start.
</para>
</listitem>
diff -r 5af127be4a67 doc/src/sgml/installation.sgml
--- a/doc/src/sgml/installation.sgml Mon Nov 23 09:06:21 2009 +0100
+++ b/doc/src/sgml/installation.sgml Fri Dec 04 21:04:34 2009 +0100
@@ -32,8 +32,9 @@
mkdir /usr/local/pgsql/data
chown postgres /usr/local/pgsql/data
su - postgres
-/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
-/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data >logfile 2>&1 &
+
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data initdb
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
/usr/local/pgsql/bin/createdb test
/usr/local/pgsql/bin/psql test
</synopsis>
@@ -465,7 +466,7 @@
execute these commands while logged in to the special database user
account (which you already have if you are upgrading).
<programlisting>
-<userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
+<userinput>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data initdb</>
</programlisting>
</para>
</step>
@@ -482,7 +483,7 @@
Start the database server, again using the special database user
account:
<programlisting>
-<userinput>/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data</>
+<userinput>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start</>
</programlisting>
</para>
</step>
@@ -1851,15 +1852,15 @@
<step>
<para>
- Create a database installation with the <command>initdb</>
- command. To run <command>initdb</> you must be logged in to your
+ Create a database installation with the <command>pg_ctl initdb</>
+ command. To run <command>pg_ctl initdb</> you must be logged in to your
<productname>PostgreSQL</> server account. It will not work as
root.
<screen>
root# <userinput>mkdir /usr/local/pgsql/data</>
root# <userinput>chown postgres /usr/local/pgsql/data</>
root# <userinput>su - postgres</>
-postgres$ <userinput>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</>
+postgres$ <userinput>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data/ initdb</>
</screen>
</para>
@@ -1868,14 +1869,14 @@
will be stored. You can use any path you want, it does not have
to be under the installation directory. Just make sure that the
server account can write to the directory (or create it, if it
- doesn't already exist) before starting <command>initdb</>, as
+ doesn't already exist) before starting <command>pg_ctl initdb</>, as
illustrated here.
</para>
</step>
<step>
<para>
- At this point, if you did not use the <command>initdb</> <literal>-A</>
+ At this point, if you did not use the <command>pg_ctl initdb</> <literal>-A</>
option, you might want to modify <filename>pg_hba.conf</> to control
local access to the server before you start it. The default is to
trust all local users.
@@ -1884,11 +1885,11 @@
<step>
<para>
- The previous <command>initdb</> step should have told you how to
+ The previous <command>pg_ctl initdb</> step should have told you how to
start up the database server. Do so now. The command should look
something like:
<programlisting>
-/usr/local/pgsql/bin/postgres -D /usr/local/pgsql/data
+/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data start
</programlisting>
This will start the server in the foreground. To put the server
in the background use something like:
@@ -2463,7 +2464,7 @@
To do this, enter the command <literal>/usr/sbin/cygserver
&</literal>. This program needs to be running anytime you
start the PostgreSQL server or initialize a database cluster
- (<command>initdb</command>). The
+ (<command>pg_ctl initdb</command>). The
default <command>cygserver</command> configuration may need to
be changed (e.g., increase <symbol>SEMMNS</symbol>) to prevent
PostgreSQL from failing due to a lack of system resources.
@@ -2522,7 +2523,7 @@
(GNU yacc). We also recommend making sure you are fairly
up-to-date on HP patches. At a minimum, if you are building 64
bit binaries on on HP-UX 11.11 you may need PHSS_30966 (11.11) or a
- successor patch otherwise <command>initdb</command> may hang:
+ successor patch otherwise <command>pg_ctl initdb</command> may hang:
<literallayout>
PHSS_30966 s700_800 ld(1) and linker tools cumulative patch
</literallayout>
diff -r 5af127be4a67 doc/src/sgml/manage-ag.sgml
--- a/doc/src/sgml/manage-ag.sgml Mon Nov 23 09:06:21 2009 +0100
+++ b/doc/src/sgml/manage-ag.sgml Fri Dec 04 21:04:34 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 database cluster initialization.
+ 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,9 +195,9 @@
<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
+ should never be changed after database cluster initialization.
+ 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
@@ -453,8 +452,8 @@
</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 database cluster initialization.
+ 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 5af127be4a67 doc/src/sgml/ref/initdb.sgml
--- a/doc/src/sgml/ref/initdb.sgml Mon Nov 23 09:06:21 2009 +0100
+++ b/doc/src/sgml/ref/initdb.sgml Fri Dec 04 21:04:34 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 5af127be4a67 doc/src/sgml/ref/pg_ctl-ref.sgml
--- a/doc/src/sgml/ref/pg_ctl-ref.sgml Mon Nov 23 09:06:21 2009 +0100
+++ b/doc/src/sgml/ref/pg_ctl-ref.sgml Fri Dec 04 21:04:34 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 5af127be4a67 doc/src/sgml/runtime.sgml
--- a/doc/src/sgml/runtime.sgml Mon Nov 23 09:06:21 2009 +0100
+++ b/doc/src/sgml/runtime.sgml Fri Dec 04 21:04:34 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 5af127be4a67 doc/src/sgml/xfunc.sgml
--- a/doc/src/sgml/xfunc.sgml Mon Nov 23 09:06:21 2009 +0100
+++ b/doc/src/sgml/xfunc.sgml Fri Dec 04 21:04:34 2009 +0100
@@ -1353,7 +1353,7 @@
<para>
Normally, all internal functions present in the
- server are declared during the initialization of the database cluster (<command>initdb</command>),
+ server are declared during the initialization of the database cluster,
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>
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.
--
Greg Smith 2ndQuadrant Baltimore, MD
PostgreSQL Training, Services and Support
greg@2ndQuadrant.com www.2ndQuadrant.com
Greg Smith <greg@2ndquadrant.com> writes:
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.
That's easily dealt with ;-) ... just rip out all those parts of the
diff. I think all that needs to be done in the docs is to list the initdb
option in the pg_ctl reference page.
If you think it's code-complete, let's just commit the code and not
try to have a re-education project going on with the docs.
regards, tom lane
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:
Show quoted text
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.
Attachments:
pg_init_doc_02.patchtext/x-patch; CHARSET=US-ASCII; name=pg_init_doc_02.patchDownload
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
Zdenek Kotala wrote:
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.
That looks much better. There's only one bit that sticks out oddly now:
+ 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. What is that supposed to mean exactly?
--
Greg Smith 2ndQuadrant Baltimore, MD
PostgreSQL Training, Services and Support
greg@2ndQuadrant.com www.2ndQuadrant.com
Greg Smith píše v út 08. 12. 2009 v 22:44 -0500:
Zdenek Kotala wrote:
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.That looks much better. There's only one bit that sticks out oddly now:
+ 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.What is that supposed to mean exactly?
Ahh, It is somethink what I want to do, but it is not ready yet in this
patch, but I already documented it. Idea is to install initdb and
postgres into libexecdir and packager can select if libexecdir will be
equal bindir or not.
The paragraph should be removed at this moment. Shell I send modified
patch or does committer remove it before commit?
thanks Zdenek
On Dec 9, 2009, at 8:32 AM, Zdenek Kotala <Zdenek.Kotala@Sun.COM> wrote:
Greg Smith píše v út 08. 12. 2009 v 22:44 -0500:
Zdenek Kotala wrote:
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.That looks much better. There's only one bit that sticks out oddly
now:+ 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.What is that supposed to mean exactly?
Ahh, It is somethink what I want to do, but it is not ready yet in
this
patch, but I already documented it. Idea is to install initdb and
postgres into libexecdir and packager can select if libexecdir will be
equal bindir or not.The paragraph should be removed at this moment. Shell I send modified
patch or does committer remove it before commit?
I think Peter claimed this one but as far as I am concerned, I would
always rather have an updated patch.
...Robert
Robert Haas píše v st 09. 12. 2009 v 08:56 -0500:
On Dec 9, 2009, at 8:32 AM, Zdenek Kotala <Zdenek.Kotala@Sun.COM> wrote:
<snip>
Ahh, It is somethink what I want to do, but it is not ready yet in
this
patch, but I already documented it. Idea is to install initdb and
postgres into libexecdir and packager can select if libexecdir will be
equal bindir or not.The paragraph should be removed at this moment. Shell I send modified
patch or does committer remove it before commit?I think Peter claimed this one but as far as I am concerned, I would
always rather have an updated patch.
OK, here it is.
Thanks Zdenek
Attachments:
pg_init_doc_03.patchtext/x-patch; CHARSET=US-ASCII; name=pg_init_doc_03.patchDownload
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 Wed Dec 09 15:17:54 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 Wed Dec 09 15:17:54 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 Wed Dec 09 15:17:54 2009 +0100
@@ -106,6 +106,11 @@
More details can be found in <xref linkend="multibyte">.
</para>
+ <para>
+ Note: The <command>initdb</command> might be also invoked by
+ <command>pg_ctl initdb</command>.
+ </para>
+
</refsect1>
<refsect1>
@@ -314,6 +319,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 Wed Dec 09 15:17:54 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 Wed Dec 09 15:17:54 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 Wed Dec 09 15:17:54 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
On ons, 2009-12-09 at 15:18 +0100, Zdenek Kotala wrote:
Robert Haas píše v st 09. 12. 2009 v 08:56 -0500:
On Dec 9, 2009, at 8:32 AM, Zdenek Kotala <Zdenek.Kotala@Sun.COM> wrote:
<snip>
Ahh, It is somethink what I want to do, but it is not ready yet in
this
patch, but I already documented it. Idea is to install initdb and
postgres into libexecdir and packager can select if libexecdir will be
equal bindir or not.The paragraph should be removed at this moment. Shell I send modified
patch or does committer remove it before commit?I think Peter claimed this one but as far as I am concerned, I would
always rather have an updated patch.OK, here it is.
Committed with some adjustments.