rdelaage
/
postgresql
mirror of https://git.postgresql.org/git/postgresql.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
postgresql/doc/src/sgml/ref/initdb.sgml

531 lines
18 KiB
Plaintext
Raw Normal View History

Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
<!--
Remove cvs keywords from all files.
2010-09-20 22:08:53 +02:00
doc/src/sgml/ref/initdb.sgml
Use PostgreSQL consistantly throughout docs. Before, usage was split evenly between Postgres and PostgreSQL.
2001-12-08 04:24:40 +01:00
PostgreSQL documentation
Complete merge of all old man page information. ecpg reference page still needs formatting.
1999-07-22 17:09:15 +02:00
-->
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refentry id="app-initdb">
doc: Improve DocBook XML validity DocBook XML is superficially compatible with DocBook SGML but has a slightly stricter DTD that we have been violating in a few cases. Although XSLT doesn't care whether the document is valid, the style sheets don't necessarily process invalid documents correctly, so we need to work toward fixing this. This first commit moves the indexterms in refentry elements to an allowed position. It has no impact on the output.
2014-02-24 03:25:35 +01:00
<indexterm zone="app-initdb">
<primary>initdb</primary>
</indexterm>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refmeta>
Remove unnecessary xref endterm attributes and title ids The endterm attribute is mainly useful when the toolchain does not support automatic link target text generation for a particular situation. In the past, this was required by the man page tools for all reference page links, but that is no longer the case, and it now actually gets in the way of proper automatic link text generation. The only remaining use cases are currently xrefs to refsects.
2010-04-03 09:23:02 +02:00
<refentrytitle>initdb</refentrytitle>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<manvolnum>1</manvolnum>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refmiscinfo>Application</refmiscinfo>
</refmeta>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refnamediv>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<refname>initdb</refname>
Put some kind of grammatical uniformity in the <refpurpose> lines.
2001-09-03 14:57:50 +02:00
<refpurpose>create a new <productname>PostgreSQL</productname> database cluster</refpurpose>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refnamediv>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<refsynopsisdiv>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<cmdsynopsis>
<command>initdb</command>
Improve wording of initdb and pg_controldata manual pages. gabrielle <gorthx@gmail.com>
2011-03-09 15:18:44 +01:00
<arg rep="repeat"><replaceable>option</replaceable></arg>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<group choice="plain">
Improve markup of cmdsynopsis elements Add more markup in particular so that the command options appear consistently in monospace in the HTML output. On the vacuumdb reference page, remove listing all the possible options in the synopsis. They have become too many now; we have the detailed options list for that.
2012-04-30 20:15:48 +02:00
<group choice="opt">
doc: Fix for too many brackets in command synopses on man pages The default for the choice attribute of the <arg> element is "opt", which would normally put the argument inside brackets. But the DSSSL stylesheets contain a hack that treats <arg> directly inside <group> specially, so that <group><arg>-x</arg><arg>-y</arg></group> comes out as [ -x | -y ] rather than [ [-x] | [-y] ], which it would technically be. But when building man pages, this doesn't work, and so the command synopses on the man pages contain lots of extra brackets. By putting choice="opt" or choice="plain" explicitly on every <arg> and <group> element, we avoid any toolchain dependencies like that, and it also makes it clearer in the source code what is meant. In passing, make some small corrections in the documentation about which arguments are really optional or not.
2012-05-03 21:50:04 +02:00
<arg choice="plain"><option>--pgdata</option></arg>
<arg choice="plain"><option>-D</option></arg>
Improve markup of cmdsynopsis elements Add more markup in particular so that the command options appear consistently in monospace in the HTML output. On the vacuumdb reference page, remove listing all the possible options in the synopsis. They have become too many now; we have the detailed options list for that.
2012-04-30 20:15:48 +02:00
</group>
<replaceable> directory</replaceable>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
</group>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
</cmdsynopsis>
</refsynopsisdiv>
Convert SGML IDs to lower case IDs in SGML are case insensitive, and we have accumulated a mix of upper and lower case IDs, including different variants of the same ID. In XML, these will be case sensitive, so we need to fix up those differences. Going to all lower case seems most straightforward, and the current build process already makes all anchors and lower case anyway during the SGML->XML conversion, so this doesn't create any difference in the output right now. A future XML-only build process would, however, maintain any mixed case ID spellings in the output, so that is another reason to clean this up beforehand. Author: Alexander Lakhin <exclusion@gmail.com>
2017-10-20 03:16:39 +02:00
<refsect1 id="r1-app-initdb-1">
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<title>
Description
</title>
<para>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
<command>initdb</command> creates a new
Another big editing pass for consistent content and presentation.
2003-03-24 15:32:51 +01:00
<productname>PostgreSQL</productname> database cluster. A database
cluster is a collection of databases that are managed by a single
server instance.
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
</para>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<para>
Update initdb locale/encoding documentation description. Backpatch to 8.0.X.
2005-02-22 03:54:19 +01:00
Creating a database cluster consists of creating the directories in
which the database data will live, generating the shared catalog
tables (tables that belong to the whole cluster rather than to any
particular database), and creating the <literal>template1</literal>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
and <literal>postgres</literal> databases. When you later create a
new database, everything in the <literal>template1</literal> database is
Cause initdb to create a third standard database "postgres", which unlike template0 and template1 does not have any special status in terms of backend functionality. However, all external utilities such as createuser and createdb now connect to "postgres" instead of template1, and the documentation is changed to encourage people to use "postgres" instead of template1 as a play area. This should fix some longstanding gotchas involving unexpected propagation of database objects by createdb (when you used template1 without understanding the implications), as well as ameliorating the problem that CREATE DATABASE is unhappy if anyone else is connected to template1. Patch by Dave Page, minor editing by Tom Lane. All per recent pghackers discussions.
2005-06-21 06:02:34 +02:00
copied. (Therefore, anything installed in <literal>template1</literal>
is automatically copied into each database created later.)
The <literal>postgres</literal> database is a default database meant
for use by users, utilities and third party applications.
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
</para>
Locale support is on by default. The choice of locale is done in initdb and/or with GUC variables.
2002-04-03 07:39:33 +02:00
<para>
Update initdb locale/encoding documentation description. Backpatch to 8.0.X.
2005-02-22 03:54:19 +01:00
Although <command>initdb</command> will attempt to create the
specified data directory, it might not have permission if the parent
directory of the desired data directory is root-owned. To initialize
in such a setup, create an empty data directory as root, then use
<command>chown</command> to assign ownership of that directory to the
database user account, then <command>su</command> to become the
database user to run <command>initdb</command>.
Locale support is on by default. The choice of locale is done in initdb and/or with GUC variables.
2002-04-03 07:39:33 +02:00
</para>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<para>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
<command>initdb</command> must be run as the user that will own the
server process, because the server needs to have access to the
files and directories that <command>initdb</command> creates.
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
Since the server cannot be run as root, you must not run
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
<command>initdb</command> as root either. (It will in fact refuse
to do so.)
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
</para>
Allow group access on PGDATA Allow the cluster to be optionally init'd with read access for the group. This means a relatively non-privileged user can perform a backup of the cluster without requiring write privileges, which enhances security. The mode of PGDATA is used to determine whether group permissions are enabled for directory and file creates. This method was chosen as it's simple and works well for the various utilities that write into PGDATA. Changing the mode of PGDATA manually will not automatically change the mode of all the files contained therein. If the user would like to enable group access on an existing cluster then changing the mode of all the existing files will be required. Note that pg_upgrade will automatically change the mode of all migrated files if the new cluster is init'd with the -g option. Tests are included for the backend and all the utilities which operate on the PG data directory to ensure that the correct mode is set based on the data directory permissions. Author: David Steele <david@pgmasters.net> Reviewed-By: Michael Paquier, with discussion amongst many others. Discussion: https://postgr.es/m/ad346fe6-b23e-59f1-ecb7-0e08390ad629%40pgmasters.net
2018-04-07 23:45:39 +02:00
<para>
For security reasons the new cluster created by <command>initdb</command>
will only be accessible by the cluster owner by default. The
<option>--allow-group-access</option> option allows any user in the same
group as the cluster owner to read files in the cluster. This is useful
for performing backups as a non-privileged user.
</para>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<para>
Update initdb locale/encoding documentation description. Backpatch to 8.0.X.
2005-02-22 03:54:19 +01:00
<command>initdb</command> initializes the database cluster's default
Make LC_COLLATE and LC_CTYPE database-level settings. Collation and ctype are now more like encoding, stored in new datcollate and datctype columns in pg_database. This is a stripped-down version of Radek Strnad's patch, with further changes by me.
2008-09-23 11:20:39 +02:00
locale and character set encoding. The character set encoding,
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
collation order (<literal>LC_COLLATE</literal>) and character set classes
(<literal>LC_CTYPE</literal>, e.g. upper, lower, digit) can be set separately
Make LC_COLLATE and LC_CTYPE database-level settings. Collation and ctype are now more like encoding, stored in new datcollate and datctype columns in pg_database. This is a stripped-down version of Radek Strnad's patch, with further changes by me.
2008-09-23 11:20:39 +02:00
for a database when it is created. <command>initdb</command> determines
those settings for the <literal>template1</literal> database, which will
serve as the default for all other databases.
</para>
<para>
To alter the default collation order or character set classes, use the
<option>--lc-collate</option> and <option>--lc-ctype</option> options.
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Collation orders other than <literal>C</literal> or <literal>POSIX</literal> also have
Make LC_COLLATE and LC_CTYPE database-level settings. Collation and ctype are now more like encoding, stored in new datcollate and datctype columns in pg_database. This is a stripped-down version of Radek Strnad's patch, with further changes by me.
2008-09-23 11:20:39 +02:00
a performance penalty. For these reasons it is important to choose the
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
right locale when running <command>initdb</command>.
Make LC_COLLATE and LC_CTYPE database-level settings. Collation and ctype are now more like encoding, stored in new datcollate and datctype columns in pg_database. This is a stripped-down version of Radek Strnad's patch, with further changes by me.
2008-09-23 11:20:39 +02:00
</para>
<para>
The remaining locale categories can be changed later when the server
is started. You can also use <option>--locale</option> to set the
default for all locale categories, including collation order and
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
character set classes. All server locale values (<literal>lc_*</literal>) can
be displayed via <command>SHOW ALL</command>.
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
More details can be found in <xref linkend="locale"/>.
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
</para>
Update initdb locale/encoding documentation description. Backpatch to 8.0.X.
2005-02-22 03:54:19 +01:00
<para>
Make LC_COLLATE and LC_CTYPE database-level settings. Collation and ctype are now more like encoding, stored in new datcollate and datctype columns in pg_database. This is a stripped-down version of Radek Strnad's patch, with further changes by me.
2008-09-23 11:20:39 +02:00
To alter the default encoding, use the <option>--encoding</option>.
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
More details can be found in <xref linkend="multibyte"/>.
Update initdb locale/encoding documentation description. Backpatch to 8.0.X.
2005-02-22 03:54:19 +01:00
</para>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
</refsect1>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<refsect1>
<title>Options</title>
Add new information for utility commands. Haven't yet done cleardbdir, ipcclean, pg_passwd, and pg_upgrade. Add reference info for the SQL VACUUM command (oops, forgot it earlier).
1998-10-05 04:54:45 +02:00
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<para>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<variablelist>
Add docs for initdb --auth.
2004-08-01 08:19:26 +02:00
<varlistentry>
<term><option>-A <replaceable class="parameter">authmethod</replaceable></option></term>
<term><option>--auth=<replaceable class="parameter">authmethod</replaceable></option></term>
<listitem>
<para>
Enable replication connections by default in pg_hba.conf initdb now initializes a pg_hba.conf that allows replication connections from the local host, same as it does for regular connections. The connecting user still needs to have the REPLICATION attribute or be a superuser. The intent is to allow pg_basebackup from the local host to succeed without requiring additional configuration. Michael Paquier <michael.paquier@gmail.com> and me
2017-03-09 14:27:16 +01:00
This option specifies the default authentication method for local
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
users used in <filename>pg_hba.conf</filename> (<literal>host</literal>
Enable replication connections by default in pg_hba.conf initdb now initializes a pg_hba.conf that allows replication connections from the local host, same as it does for regular connections. The connecting user still needs to have the REPLICATION attribute or be a superuser. The intent is to allow pg_basebackup from the local host to succeed without requiring additional configuration. Michael Paquier <michael.paquier@gmail.com> and me
2017-03-09 14:27:16 +01:00
and <literal>local</literal> lines). <command>initdb</command> will
prepopulate <filename>pg_hba.conf</filename> entries using the
specified authentication method for non-replication as well as
replication connections.
</para>
initdb: Change authentication defaults Change the defaults for the pg_hba.conf generated by initdb to "peer" for local (if supported, else "md5") and "md5" for host. (Changing from "md5" to SCRAM is left as a separate exercise.) "peer" is currently not supported on AIX, HP-UX, and Windows. Users on those operating systems will now either have to provide a password to initdb or choose a different authentication method when running initdb. Reviewed-by: Julien Rouhaud <rjuju123@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/bec17f0a-ddb1-8b95-5e69-368d9d0a3390%40postgresql.org
2019-07-22 14:40:55 +02:00
<para>
The default is <literal>peer</literal> for Unix-domain socket
connections on operating systems that support it, otherwise
<literal>md5</literal>, and <literal>md5</literal> for TCP/IP
connections.
</para>
<para>
When running <command>initdb</command> on a platform that does not
support <literal>peer</literal> authentication, either a password must
be provided (see <option>-W</option> and other options) or a different
authentication method must be chosen, otherwise
<command>initdb</command> will error.
</para>
Enable replication connections by default in pg_hba.conf initdb now initializes a pg_hba.conf that allows replication connections from the local host, same as it does for regular connections. The connecting user still needs to have the REPLICATION attribute or be a superuser. The intent is to allow pg_basebackup from the local host to succeed without requiring additional configuration. Michael Paquier <michael.paquier@gmail.com> and me
2017-03-09 14:27:16 +01:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Do not use <literal>trust</literal> unless you trust all local users on your
initdb: Change authentication defaults Change the defaults for the pg_hba.conf generated by initdb to "peer" for local (if supported, else "md5") and "md5" for host. (Changing from "md5" to SCRAM is left as a separate exercise.) "peer" is currently not supported on AIX, HP-UX, and Windows. Users on those operating systems will now either have to provide a password to initdb or choose a different authentication method when running initdb. Reviewed-by: Julien Rouhaud <rjuju123@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/bec17f0a-ddb1-8b95-5e69-368d9d0a3390%40postgresql.org
2019-07-22 14:40:55 +02:00
system.
initdb: Add options --auth-local and --auth-host reviewed by Robert Haas and Pavel Stehule
2012-02-01 20:18:55 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--auth-host=<replaceable class="parameter">authmethod</replaceable></option></term>
<listitem>
<para>
This option specifies the authentication method for local users via
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
TCP/IP connections used in <filename>pg_hba.conf</filename>
initdb: Add options --auth-local and --auth-host reviewed by Robert Haas and Pavel Stehule
2012-02-01 20:18:55 +01:00
(<literal>host</literal> lines).
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--auth-local=<replaceable class="parameter">authmethod</replaceable></option></term>
<listitem>
<para>
This option specifies the authentication method for local users via
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
Unix-domain socket connections used in <filename>pg_hba.conf</filename>
initdb: Add options --auth-local and --auth-host reviewed by Robert Haas and Pavel Stehule
2012-02-01 20:18:55 +01:00
(<literal>local</literal> lines).
Add docs for initdb --auth.
2004-08-01 08:19:26 +02:00
</para>
</listitem>
</varlistentry>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<varlistentry>
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<listitem>
<para>
Another big editing pass for consistent content and presentation.
2003-03-24 15:32:51 +01:00
This option specifies the directory where the database cluster
Refine some things to create better looking man pages.
2000-12-26 00:15:27 +01:00
should be stored. This is the only information required by
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
<command>initdb</command>, but you can avoid writing it by
Refine some things to create better looking man pages.
2000-12-26 00:15:27 +01:00
setting the <envar>PGDATA</envar> environment variable, which
can be convenient since the database server
Merge postmaster and postgres command into just postgres. postmaster symlink is kept for now for compatibility. To call single-user mode, use postgres --single.
2006-06-18 17:38:37 +02:00
(<command>postgres</command>) can find the database
Refine some things to create better looking man pages.
2000-12-26 00:15:27 +01:00
directory later by the same variable.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
</listitem>
</varlistentry>
Add new information for utility commands. Haven't yet done cleardbdir, ipcclean, pg_passwd, and pg_upgrade. Add reference info for the SQL VACUUM command (oops, forgot it earlier).
1998-10-05 04:54:45 +02:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<varlistentry>
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
<term><option>-E <replaceable class="parameter">encoding</replaceable></option></term>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
This is my -- hopefully sufficiently portable -- attempt at cleaning out initdb. No more obscure dependencies on environment variables or paths. It now finds the templates and the right postgres itself (with cmd line options as fallback). It also no longer depends on $USER (su safe), and doesn't advertise that --username allows you to install the db as a different user, since that doesn't work anyway. Also, recovery and cleanup on all errors. Consistent options, clearer documentation. Please take a look at this and adopt it if you feel it's safe enough. I have simulated all the stupid circumstances I could think of, but you never know with shell scripts. Oh yeah, you can give the postgres user a default password now. -- Peter Eisentraut Sernanders väg 10:115
1999-12-17 02:05:31 +01:00
<listitem>
<para>
proof-reading
2001-11-28 21:49:10 +01:00
Selects the encoding of the template database. This will also
Improve the locale and character set docs, add some <xref>s pointing to the character set docs where appropriate, and improve the postmaster reference page. Character set cross-refs suggested by Gavin Kistner.
2004-03-23 03:47:35 +01:00
be the default encoding of any database you create later,
Detect locale/encoding mismatch in initdb, or pick a suitable encoding automatically if none was specified.
2004-07-14 19:55:10 +02:00
unless you override it there. The default is derived from the locale, or
<literal>SQL_ASCII</literal> if that does not work. The character sets supported by
Improve the locale and character set docs, add some <xref>s pointing to the character set docs where appropriate, and improve the postmaster reference page. Character set cross-refs suggested by Gavin Kistner.
2004-03-23 03:47:35 +01:00
the <productname>PostgreSQL</productname> server are described
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
in <xref linkend="multibyte-charset-supported"/>.
This is my -- hopefully sufficiently portable -- attempt at cleaning out initdb. No more obscure dependencies on environment variables or paths. It now finds the templates and the right postgres itself (with cmd line options as fallback). It also no longer depends on $USER (su safe), and doesn't advertise that --username allows you to install the db as a different user, since that doesn't work anyway. Also, recovery and cleanup on all errors. Consistent options, clearer documentation. Please take a look at this and adopt it if you feel it's safe enough. I have simulated all the stupid circumstances I could think of, but you never know with shell scripts. Oh yeah, you can give the postgres user a default password now. -- Peter Eisentraut Sernanders väg 10:115
1999-12-17 02:05:31 +01:00
</para>
</listitem>
</varlistentry>
Allow group access on PGDATA Allow the cluster to be optionally init'd with read access for the group. This means a relatively non-privileged user can perform a backup of the cluster without requiring write privileges, which enhances security. The mode of PGDATA is used to determine whether group permissions are enabled for directory and file creates. This method was chosen as it's simple and works well for the various utilities that write into PGDATA. Changing the mode of PGDATA manually will not automatically change the mode of all the files contained therein. If the user would like to enable group access on an existing cluster then changing the mode of all the existing files will be required. Note that pg_upgrade will automatically change the mode of all migrated files if the new cluster is init'd with the -g option. Tests are included for the backend and all the utilities which operate on the PG data directory to ensure that the correct mode is set based on the data directory permissions. Author: David Steele <david@pgmasters.net> Reviewed-By: Michael Paquier, with discussion amongst many others. Discussion: https://postgr.es/m/ad346fe6-b23e-59f1-ecb7-0e08390ad629%40pgmasters.net
2018-04-07 23:45:39 +02:00
<varlistentry id="app-initdb-allow-group-access" xreflabel="group access">
<term><option>-g</option></term>
<term><option>--allow-group-access</option></term>
<listitem>
<para>
Allows users in the same group as the cluster owner to read all cluster
Clarify behavior of initdb's --allow-group-access on Windows in docs The option is ignored on Windows, and GUC data_directory_mode already mentioned that within its description in the documentation. Author: Michael Paquier Reported-by: Haribabu Kommi, David Steele Discussion: https://postgr.es/m/CAJrrPGefxTG43yk6BrOC7ZcMnCTccG9+inCSncvyys_t8Ev9cQ@mail.gmail.com Backpatch-through: 11
2019-02-04 01:57:20 +01:00
files created by <command>initdb</command>. This option is ignored
on <productname>Windows</productname> as it does not support
<acronym>POSIX</acronym>-style group permissions.
Allow group access on PGDATA Allow the cluster to be optionally init'd with read access for the group. This means a relatively non-privileged user can perform a backup of the cluster without requiring write privileges, which enhances security. The mode of PGDATA is used to determine whether group permissions are enabled for directory and file creates. This method was chosen as it's simple and works well for the various utilities that write into PGDATA. Changing the mode of PGDATA manually will not automatically change the mode of all the files contained therein. If the user would like to enable group access on an existing cluster then changing the mode of all the existing files will be required. Note that pg_upgrade will automatically change the mode of all migrated files if the new cluster is init'd with the -g option. Tests are included for the backend and all the utilities which operate on the PG data directory to ensure that the correct mode is set based on the data directory permissions. Author: David Steele <david@pgmasters.net> Reviewed-By: Michael Paquier, with discussion amongst many others. Discussion: https://postgr.es/m/ad346fe6-b23e-59f1-ecb7-0e08390ad629%40pgmasters.net
2018-04-07 23:45:39 +02:00
</para>
</listitem>
</varlistentry>
Allow I/O reliability checks using 16-bit checksums Checksums are set immediately prior to flush out of shared buffers and checked when pages are read in again. Hint bit setting will require full page write when block is dirtied, which causes various infrastructure changes. Extensive comments, docs and README. WARNING message thrown if checksum fails on non-all zeroes page; ERROR thrown but can be disabled with ignore_checksum_failure = on. Feature enabled by an initdb option, since transition from option off to option on is long and complex and has not yet been implemented. Default is not to use checksums. Checksum used is WAL CRC-32 truncated to 16-bits. Simon Riggs, Jeff Davis, Greg Smith Wide input and assistance from many community members. Thank you.
2013-03-22 14:54:07 +01:00
<varlistentry id="app-initdb-data-checksums" xreflabel="data checksums">
<term><option>-k</option></term>
<term><option>--data-checksums</option></term>
<listitem>
<para>
Use checksums on data pages to help detect corruption by the
I/O system that would otherwise be silent. Enabling checksums
Simplify description of --data-checksums in documentation of initdb The documentation mentioned that data checksums cannot be changed after initialization, which is not true as pg_checksums can do that with its --enable option introduced in v12. This simply removes the sentence telling so. Reported-by: Basil Bourque Author: Michael Paquier Reviewed-by: Daniel Gustafsson Discussion: https://postgr.es/m/15909-e9d74271f1647472@postgresql.org Backpatch-through: 12
2019-07-18 03:05:59 +02:00
may incur a noticeable performance penalty. If set, checksums
are calculated for all objects, in all databases. All checksum
failures will be reported in the
<xref linkend="pg-stat-database-view"/> view.
Allow I/O reliability checks using 16-bit checksums Checksums are set immediately prior to flush out of shared buffers and checked when pages are read in again. Hint bit setting will require full page write when block is dirtied, which causes various infrastructure changes. Extensive comments, docs and README. WARNING message thrown if checksum fails on non-all zeroes page; ERROR thrown but can be disabled with ignore_checksum_failure = on. Feature enabled by an initdb option, since transition from option off to option on is long and complex and has not yet been implemented. Default is not to use checksums. Checksum used is WAL CRC-32 truncated to 16-bits. Simon Riggs, Jeff Davis, Greg Smith Wide input and assistance from many community members. Thank you.
2013-03-22 14:54:07 +01:00
</para>
</listitem>
</varlistentry>
Locale support is on by default. The choice of locale is done in initdb and/or with GUC variables.
2002-04-03 07:39:33 +02:00
<varlistentry>
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
<term><option>--locale=<replaceable>locale</replaceable></option></term>
Locale support is on by default. The choice of locale is done in initdb and/or with GUC variables.
2002-04-03 07:39:33 +02:00
<listitem>
<para>
Sets the default locale for the database cluster. If this
option is not specified, the locale is inherited from the
Improve the locale and character set docs, add some <xref>s pointing to the character set docs where appropriate, and improve the postmaster reference page. Character set cross-refs suggested by Gavin Kistner.
2004-03-23 03:47:35 +01:00
environment that <command>initdb</command> runs in. Locale
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
support is described in <xref linkend="locale"/>.
Locale support is on by default. The choice of locale is done in initdb and/or with GUC variables.
2002-04-03 07:39:33 +02:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
<term><option>--lc-collate=<replaceable>locale</replaceable></option></term>
<term><option>--lc-ctype=<replaceable>locale</replaceable></option></term>
<term><option>--lc-messages=<replaceable>locale</replaceable></option></term>
<term><option>--lc-monetary=<replaceable>locale</replaceable></option></term>
<term><option>--lc-numeric=<replaceable>locale</replaceable></option></term>
<term><option>--lc-time=<replaceable>locale</replaceable></option></term>
Locale support is on by default. The choice of locale is done in initdb and/or with GUC variables.
2002-04-03 07:39:33 +02:00
<listitem>
<para>
Like <option>--locale</option>, but only sets the locale in
the specified category.
</para>
</listitem>
</varlistentry>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
Add description for --no-locale and --text-search-config.
2012-03-11 00:23:20 +01:00
<varlistentry>
<term><option>--no-locale</option></term>
<listitem>
<para>
Remove tabs in SGML files
2012-03-12 15:13:42 +01:00
Equivalent to <option>--locale=C</option>.
Add description for --no-locale and --text-search-config.
2012-03-11 00:23:20 +01:00
</para>
</listitem>
</varlistentry>
Add fsync capability to initdb, and use sync_file_range() if available. Historically we have not worried about fsync'ing anything during initdb (in fact, initdb intentionally passes -F to each backend launch to prevent it from fsync'ing). But with filesystems getting more aggressive about caching data, that's not such a good plan anymore. Make initdb do a pass over the finished data directory tree to fsync everything. For testing purposes, the -N/--nosync flag can be used to restore the old behavior. Also, testing shows that on Linux, sync_file_range() is much faster than posix_fadvise() for hinting to the kernel that an fsync is coming, apparently because the latter blocks on a rather small request queue while the former doesn't. So use this function if available in initdb, and also in the backend's pg_flush_data() (where it currently will affect only the speed of CREATE DATABASE's cloning step). We will later make pg_regress invoke initdb with the --nosync flag to avoid slowing down cases such as "make check" in contrib. But let's not do so until we've shaken out any portability issues in this patch. Jeff Davis, reviewed by Andres Freund
2012-07-13 23:16:58 +02:00
<varlistentry>
<term><option>-N</option></term>
initdb pg_basebackup: Rename --noxxx options to --no-xxx --noclean and --nosync were the only options spelled without a hyphen, so change this for consistency with other options. The options in pg_basebackup have not been in a release, so we just rename them. For initdb, we retain the old variants. Vik Fearing and me
2016-10-19 18:00:00 +02:00
<term><option>--no-sync</option></term>
Add fsync capability to initdb, and use sync_file_range() if available. Historically we have not worried about fsync'ing anything during initdb (in fact, initdb intentionally passes -F to each backend launch to prevent it from fsync'ing). But with filesystems getting more aggressive about caching data, that's not such a good plan anymore. Make initdb do a pass over the finished data directory tree to fsync everything. For testing purposes, the -N/--nosync flag can be used to restore the old behavior. Also, testing shows that on Linux, sync_file_range() is much faster than posix_fadvise() for hinting to the kernel that an fsync is coming, apparently because the latter blocks on a rather small request queue while the former doesn't. So use this function if available in initdb, and also in the backend's pg_flush_data() (where it currently will affect only the speed of CREATE DATABASE's cloning step). We will later make pg_regress invoke initdb with the --nosync flag to avoid slowing down cases such as "make check" in contrib. But let's not do so until we've shaken out any portability issues in this patch. Jeff Davis, reviewed by Andres Freund
2012-07-13 23:16:58 +02:00
<listitem>
<para>
By default, <command>initdb</command> will wait for all files to be
written safely to disk. This option causes <command>initdb</command>
to return without waiting, which is faster, but means that a
subsequent operating system crash can leave the data directory
corrupt. Generally, this option is useful for testing, but should not
be used when creating a production installation.
</para>
</listitem>
</varlistentry>
Allow initdb to specify the pg_xlog directory. Euler Taveira de Oliveira
2007-01-06 20:40:00 +01:00
<varlistentry>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><option>--pwfile=<replaceable>filename</replaceable></option></term>
Allow initdb to specify the pg_xlog directory. Euler Taveira de Oliveira
2007-01-06 20:40:00 +01:00
<listitem>
<para>
Improve wording of initdb and pg_controldata manual pages. gabrielle <gorthx@gmail.com>
2011-03-09 15:18:44 +01:00
Makes <command>initdb</command> read the database superuser's password
from a file. The first line of the file is taken as the password.
Allow initdb to specify the pg_xlog directory. Euler Taveira de Oliveira
2007-01-06 20:40:00 +01:00
</para>
</listitem>
</varlistentry>
Add description for --no-locale and --text-search-config.
2012-03-11 00:23:20 +01:00
<varlistentry>
Add initdb --sync-only option to sync the data directory to durable storage. Have pg_upgrade use it, and enable server options fsync=off and full_page_writes=off. Document that users turning fsync from off to on should run initdb --sync-only. [ Previous commit was incorrectly applied as a git merge. ]
2012-12-04 04:47:59 +01:00
<term><option>-S</option></term>
<term><option>--sync-only</option></term>
<listitem>
<para>
Safely write all database files to disk and exit. This does not
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
perform any of the normal <application>initdb</application> operations.
Add initdb --sync-only option to sync the data directory to durable storage. Have pg_upgrade use it, and enable server options fsync=off and full_page_writes=off. Document that users turning fsync from off to on should run initdb --sync-only. [ Previous commit was incorrectly applied as a git merge. ]
2012-12-04 04:47:59 +01:00
</para>
</listitem>
</varlistentry>
<varlistentry>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><option>-T <replaceable>config</replaceable></option></term>
<term><option>--text-search-config=<replaceable>config</replaceable></option></term>
Add description for --no-locale and --text-search-config.
2012-03-11 00:23:20 +01:00
<listitem>
<para>
Remove tabs in SGML files
2012-03-12 15:13:42 +01:00
Sets the default text search configuration.
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
See <xref linkend="guc-default-text-search-config"/> for further information.
Add description for --no-locale and --text-search-config.
2012-03-11 00:23:20 +01:00
</para>
</listitem>
</varlistentry>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<varlistentry>
<term><option>-U <replaceable class="parameter">username</replaceable></option></term>
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
<listitem>
<para>
Selects the user name of the database superuser. This defaults
to the name of the effective user running
<command>initdb</command>. It is really not important what the
superuser's name is, but one might choose to keep the
customary name <systemitem>postgres</systemitem>, even if the operating
system user's name is different.
</para>
</listitem>
</varlistentry>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<varlistentry>
<term><option>-W</option></term>
<term><option>--pwprompt</option></term>
<listitem>
<para>
Makes <command>initdb</command> prompt for a password
to give the database superuser. If you don't plan on using password
authentication, this is not important. Otherwise you won't be
able to use password authentication until you have a password
set up.
</para>
</listitem>
</varlistentry>
Add --pwfile option to initdb, so that passwords can be set by GUI tools that aren't able to feed the password to initdb's /dev/tty. Magnus Hagander
2004-06-24 21:26:59 +02:00
Make WAL segment size configurable at initdb time. For performance reasons a larger segment size than the default 16MB can be useful. A larger segment size has two main benefits: Firstly, in setups using archiving, it makes it easier to write scripts that can keep up with higher amounts of WAL, secondly, the WAL has to be written and synced to disk less frequently. But at the same time large segment size are disadvantageous for smaller databases. So far the segment size had to be configured at compile time, often making it unrealistic to choose one fitting to a particularly load. Therefore change it to a initdb time setting. This includes a breaking changes to the xlogreader.h API, which now requires the current segment size to be configured. For that and similar reasons a number of binaries had to be taught how to recognize the current segment size. Author: Beena Emerson, editorialized by Andres Freund Reviewed-By: Andres Freund, David Steele, Kuntal Ghosh, Michael Paquier, Peter Eisentraut, Robert Hass, Tushar Ahuja Discussion: https://postgr.es/m/CAOG9ApEAcQ--1ieKbhFzXSQPw_YLmepaa4hNdnY5+ZULpt81Mw@mail.gmail.com
2017-09-20 07:03:48 +02:00
<varlistentry>
Improve wording of initdb and pg_controldata manual pages. gabrielle <gorthx@gmail.com>
2011-03-09 15:18:44 +01:00
<term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
Rename command line options for ongoing xlog -> wal conversion. initdb and pg_basebackup now have a --waldir option rather --xlogdir, and pg_basebackup now has --wal-method rather than --xlog-method.
2017-02-09 22:42:51 +01:00
<term><option>--waldir=<replaceable class="parameter">directory</replaceable></option></term>
Add --pwfile option to initdb, so that passwords can be set by GUI tools that aren't able to feed the password to initdb's /dev/tty. Magnus Hagander
2004-06-24 21:26:59 +02:00
<listitem>
<para>
Replace "transaction log" with "write-ahead log" This makes documentation and error messages match the renaming of "xlog" to "wal" in APIs and file naming.
2017-05-12 17:49:56 +02:00
This option specifies the directory where the write-ahead log
Improve wording of initdb and pg_controldata manual pages. gabrielle <gorthx@gmail.com>
2011-03-09 15:18:44 +01:00
should be stored.
Add --pwfile option to initdb, so that passwords can be set by GUI tools that aren't able to feed the password to initdb's /dev/tty. Magnus Hagander
2004-06-24 21:26:59 +02:00
</para>
</listitem>
</varlistentry>
Improve wording of initdb and pg_controldata manual pages. gabrielle <gorthx@gmail.com>
2011-03-09 15:18:44 +01:00
doc: Move some new options into better positions on man pages
2018-06-08 05:36:04 +02:00
<varlistentry>
<term><option>--wal-segsize=<replaceable>size</replaceable></option></term>
<listitem>
<para>
Set the <firstterm>WAL segment size</firstterm>, in megabytes. This
is the size of each individual file in the WAL log. The default size
is 16 megabytes. The value must be a power of 2 between 1 and 1024
(megabytes). This option can only be set during initialization, and
cannot be changed later.
</para>
<para>
It may be useful to adjust this size to control the granularity of
WAL log shipping or archiving. Also, in databases with a high volume
of WAL, the sheer number of WAL files per directory can become a
performance and management problem. Increasing the WAL file size
will reduce the number of WAL files.
</para>
</listitem>
</varlistentry>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
</variablelist>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
<para>
Some reference page improvements initdb: Add -T option oid2name: Put options in some non-random order pg_dump: Put --section option in the right place And some additional markup and terminology improvements.
2012-05-20 00:15:55 +02:00
Other, less commonly used, options are also available:
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<variablelist>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<varlistentry>
<term><option>-d</option></term>
<term><option>--debug</option></term>
<listitem>
<para>
Remove tabs from SGML reference files, so their addition can be detected in the future.
2007-02-22 00:21:12 +01:00
Print debugging output from the bootstrap backend and a few other
Assorted reference page updates
2002-10-12 01:03:48 +02:00
messages of lesser interest for the general public.
Remove tabs from SGML reference files, so their addition can be detected in the future.
2007-02-22 00:21:12 +01:00
The bootstrap backend is the program <command>initdb</command>
uses to create the catalog tables. This option generates a tremendous
amount of extremely boring output.
Assorted reference page updates
2002-10-12 01:03:48 +02:00
</para>
</listitem>
</varlistentry>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<varlistentry>
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
<term><option>-L <replaceable class="parameter">directory</replaceable></option></term>
This is my -- hopefully sufficiently portable -- attempt at cleaning out initdb. No more obscure dependencies on environment variables or paths. It now finds the templates and the right postgres itself (with cmd line options as fallback). It also no longer depends on $USER (su safe), and doesn't advertise that --username allows you to install the db as a different user, since that doesn't work anyway. Also, recovery and cleanup on all errors. Consistent options, clearer documentation. Please take a look at this and adopt it if you feel it's safe enough. I have simulated all the stupid circumstances I could think of, but you never know with shell scripts. Oh yeah, you can give the postgres user a default password now. -- Peter Eisentraut Sernanders väg 10:115
1999-12-17 02:05:31 +01:00
<listitem>
<para>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
Specifies where <command>initdb</command> should find
Another big editing pass for consistent content and presentation.
2003-03-24 15:32:51 +01:00
its input files to initialize the database cluster. This is
Refine some things to create better looking man pages.
2000-12-26 00:15:27 +01:00
normally not necessary. You will be told if you need to
specify their location explicitly.
This is my -- hopefully sufficiently portable -- attempt at cleaning out initdb. No more obscure dependencies on environment variables or paths. It now finds the templates and the right postgres itself (with cmd line options as fallback). It also no longer depends on $USER (su safe), and doesn't advertise that --username allows you to install the db as a different user, since that doesn't work anyway. Also, recovery and cleanup on all errors. Consistent options, clearer documentation. Please take a look at this and adopt it if you feel it's safe enough. I have simulated all the stupid circumstances I could think of, but you never know with shell scripts. Oh yeah, you can give the postgres user a default password now. -- Peter Eisentraut Sernanders väg 10:115
1999-12-17 02:05:31 +01:00
</para>
</listitem>
</varlistentry>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<varlistentry>
Add more appropriate markup.
2002-09-21 20:32:54 +02:00
<term><option>-n</option></term>
initdb pg_basebackup: Rename --noxxx options to --no-xxx --noclean and --nosync were the only options spelled without a hyphen, so change this for consistency with other options. The options in pg_basebackup have not been in a release, so we just rename them. For initdb, we retain the old variants. Vik Fearing and me
2016-10-19 18:00:00 +02:00
<term><option>--no-clean</option></term>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
<listitem>
<para>
Remove tabs from SGML reference files, so their addition can be detected in the future.
2007-02-22 00:21:12 +01:00
By default, when <command>initdb</command>
determines that an error prevented it from completely creating the database
cluster, it removes any files it might have created before discovering
that it cannot finish the job. This option inhibits tidying-up and is
thus useful for debugging.
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</para>
</listitem>
</varlistentry>
Make documentation of --help and --version options more consistent Before, some places didn't document the short options (-? and -V), some documented both, some documented nothing, and they were listed in various orders. Now this is hopefully more consistent and complete.
2012-06-18 01:44:00 +02:00
</variablelist>
</para>
Document --version and --help options for all client applications (they all support it). Per report from Josh Kupershmidt
2010-02-19 15:36:45 +01:00
Make documentation of --help and --version options more consistent Before, some places didn't document the short options (-? and -V), some documented both, some documented nothing, and they were listed in various orders. Now this is hopefully more consistent and complete.
2012-06-18 01:44:00 +02:00
<para>
Other options:
<variablelist>
Document --version and --help options for all client applications (they all support it). Per report from Josh Kupershmidt
2010-02-19 15:36:45 +01:00
<varlistentry>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><option>-V</option></term>
<term><option>--version</option></term>
Document --version and --help options for all client applications (they all support it). Per report from Josh Kupershmidt
2010-02-19 15:36:45 +01:00
<listitem>
<para>
Print the <application>initdb</application> version and exit.
</para>
</listitem>
</varlistentry>
<varlistentry>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
<term><option>-?</option></term>
<term><option>--help</option></term>
Document --version and --help options for all client applications (they all support it). Per report from Josh Kupershmidt
2010-02-19 15:36:45 +01:00
<listitem>
<para>
Show help about <application>initdb</application> command line
arguments, and exit.
</para>
</listitem>
</varlistentry>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</variablelist>
</para>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
</refsect1>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<refsect1>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
<title>Environment</title>
<variablelist>
<varlistentry>
<term><envar>PGDATA</envar></term>
<listitem>
<para>
Another big editing pass for consistent content and presentation.
2003-03-24 15:32:51 +01:00
Specifies the directory where the database cluster is to be
Update reference documentation on may/can/might: Standard English uses "may", "can", and "might" in different ways: may - permission, "You may borrow my rake." can - ability, "I can lift that log." might - possibility, "It might rain today." Unfortunately, in conversational English, their use is often mixed, as in, "You may use this variable to do X", when in fact, "can" is a better choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
stored; can be overridden using the <option>-D</option> option.
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
</para>
</listitem>
</varlistentry>
Mention the TZ environment variable for initdb Daniel Gustafsson
2014-11-16 15:48:30 +01:00
Unified logging system for command-line programs This unifies the various ad hoc logging (message printing, error printing) systems used throughout the command-line programs. Features: - Program name is automatically prefixed. - Message string does not end with newline. This removes a common source of inconsistencies and omissions. - Additionally, a final newline is automatically stripped, simplifying use of PQerrorMessage() etc., another common source of mistakes. - I converted error message strings to use %m where possible. - As a result of the above several points, more translatable message strings can be shared between different components and between frontends and backend, without gratuitous punctuation or whitespace differences. - There is support for setting a "log level". This is not meant to be user-facing, but can be used internally to implement debug or verbose modes. - Lazy argument evaluation, so no significant overhead if logging at some level is disabled. - Some color in the messages, similar to gcc and clang. Set PG_COLOR=auto to try it out. Some colors are predefined, but can be customized by setting PG_COLORS. - Common files (common/, fe_utils/, etc.) can handle logging much more simply by just using one API without worrying too much about the context of the calling program, requiring callbacks, or having to pass "progname" around everywhere. - Some programs called setvbuf() to make sure that stderr is unbuffered, even on Windows. But not all programs did that. This is now done centrally. Soft goals: - Reduces vertical space use and visual complexity of error reporting in the source code. - Encourages more deliberate classification of messages. For example, in some cases it wasn't clear without analyzing the surrounding code whether a message was meant as an error or just an info. - Concepts and terms are vaguely aligned with popular logging frameworks such as log4j and Python logging. This is all just about printing stuff out. Nothing affects program flow (e.g., fatal exits). The uses are just too varied to do that. Some existing code had wrappers that do some kind of print-and-exit, and I adapted those. I tried to keep the output mostly the same, but there is a lot of historical baggage to unwind and special cases to consider, and I might not always have succeeded. One significant change is that pg_rewind used to write all error messages to stdout. That is now changed to stderr. Reviewed-by: Donald Dong <xdong@csumb.edu> Reviewed-by: Arthur Zakirov <a.zakirov@postgrespro.ru> Discussion: https://www.postgresql.org/message-id/flat/6a609b43-4f57-7348-6480-bd022f924310@2ndquadrant.com
2019-04-01 14:24:37 +02:00
<varlistentry>
<term><envar>PG_COLOR</envar></term>
<listitem>
<para>
Specifies whether to use color in diagnostics messages. Possible values
are <literal>always</literal>, <literal>auto</literal>,
<literal>never</literal>.
</para>
</listitem>
</varlistentry>
Mention the TZ environment variable for initdb Daniel Gustafsson
2014-11-16 15:48:30 +01:00
<varlistentry>
<term><envar>TZ</envar></term>
<listitem>
<para>
doc: Add link to how to specify time zone names to initdb man page
2014-12-15 02:02:04 +01:00
Specifies the default time zone of the created database cluster. The
value should be a full time zone name
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(see <xref linkend="datatype-timezones"/>).
Mention the TZ environment variable for initdb Daniel Gustafsson
2014-11-16 15:48:30 +01:00
</para>
</listitem>
</varlistentry>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
</variablelist>
More clearly document that most PostgreSQL utilities support libpq environment variables. Backpatch to 8.2.X.
2007-02-20 19:10:59 +01:00
<para>
Don't use SGML empty tags For DocBook XML compatibility, don't use SGML empty tags (</>) anymore, replace by the full tag name. Add a warning option to catch future occurrences. Alexander Lakhin, Jürgen Purtz
2017-10-09 03:44:17 +02:00
This utility, like most other <productname>PostgreSQL</productname> utilities,
also uses the environment variables supported by <application>libpq</application>
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
(see <xref linkend="libpq-envars"/>).
More clearly document that most PostgreSQL utilities support libpq environment variables. Backpatch to 8.2.X.
2007-02-20 19:10:59 +01:00
</para>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
</refsect1>
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>
2009-12-10 07:32:28 +01:00
<refsect1>
<title>Notes</title>
<para>
<command>initdb</command> can also be invoked via
<command>pg_ctl initdb</command>.
</para>
</refsect1>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
<refsect1>
<title>See Also</title>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
<simplelist type="inline">
Convert documentation to DocBook XML Since some preparation work had already been done, the only source changes left were changing empty-element tags like <xref linkend="foo"> to <xref linkend="foo"/>, and changing the DOCTYPE. The source files are still named *.sgml, but they are actually XML files now. Renaming could be considered later. In the build system, the intermediate step to convert from SGML to XML is removed. Everything is build straight from the source files again. The OpenSP (or the old SP) package is no longer needed. The documentation toolchain instructions are updated and are much simpler now. Peter Eisentraut, Alexander Lakhin, Jürgen Purtz
2017-11-23 15:39:47 +01:00
<member><xref linkend="app-pg-ctl"/></member>
<member><xref linkend="app-postgres"/></member>
Make the world somewhat safe for (not from) DELETE FROM pg_shadow; Assign the fixed user id 1 to the user created by initdb. A stand-alone backend will always set the user id to 1. (Consequently, the name of that user is no longer important.) In stand-alone mode, the user id 1 will have implicit superuser status, to allow repairs even if there are no users defined. Print a warning message when starting in stand-alone mode when no users are defined. Disallow dropping the current user and session user. Granting/revoking superuser status also grants/revokes usecatupd. (Previously, it would never grant it back. This could lead to "deadlocks".) CREATE USER and CREATE GROUP will start allocating user ids at 100 (unless explicitly specified), to prevent accidental creation of a superuser (plus some room for future extensions).
2001-09-08 17:24:00 +02:00
</simplelist>
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refsect1>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
Fix markup for docbook2man man page generation. No big deal; fixed lots of other markup at the same time. Bigest change: make sure there is no whitespace in front of <term> contents. This will probably help the other output types too.
1999-07-06 19:16:42 +02:00
</refentry>