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/createdb.sgml

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

450 lines
14 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/createdb.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-createdb">
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-createdb">
<primary>createdb</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><application>createdb</application></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>createdb</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</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>createdb</command>
First pass over client applications documentation proofreading. gabrielle
2010-02-19 04:50:03 +01:00
<arg rep="repeat"><replaceable>connection-option</replaceable></arg>
Another big editing pass for consistent content and presentation.
2003-03-24 15:32:51 +01:00
<arg rep="repeat"><replaceable>option</replaceable></arg>
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="opt"><replaceable>dbname</replaceable>
<arg choice="opt"><replaceable>description</replaceable></arg></arg>
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
</cmdsynopsis>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
</refsynopsisdiv>
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
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +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
<refsect1 id="r1-app-createdb-1">
doc: Remove line breaks after <title> This creates unnecessary rendering problem risks, and it's inconsistent and gets copied around.
2020-06-07 13:10:18 +02:00
<title>Description</title>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
<para>
<application>createdb</application> creates a new <productname>PostgreSQL</productname>
database.
</para>
<para>
Normally, the database user who executes this command becomes the owner of
the new database.
First pass over client applications documentation proofreading. gabrielle
2010-02-19 04:50:03 +01:00
However, a different owner can be specified via the <option>-O</option>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
option, if the executing user has appropriate privileges.
</para>
<para>
Reimplement create and drop scripts in C, to reduce repetitive connections, increase robustness, add NLS, and prepare for Windows port. (vacuumdb and clusterdb will follow later.)
2003-03-18 23:19:47 +01:00
<application>createdb</application> is a wrapper around the
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
<acronym>SQL</acronym> command <link linkend="sql-createdatabase"><command>CREATE DATABASE</command></link>.
More cleanup of Diagnostics sections.
2003-09-12 02:12:47 +02:00
There is no effective difference between creating databases via
this utility and via other methods for accessing the server.
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
</para>
More cleanup of Diagnostics sections.
2003-09-12 02:12:47 +02:00
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
</refsect1>
<refsect1>
<title>Options</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
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<para>
<application>createdb</application> accepts the following command-line arguments:
New scripts for create/drop user/db from Peter Eisentraut
1999-12-04 05:53:22 +01:00
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
<varlistentry>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<term><replaceable class="parameter">dbname</replaceable></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>
Replace createdb's obsolete --location switch with --tablespace. I kept the same abbreviated letter -D, in hopes of maintaining some modicum of backwards compatibility (though it's doubtful whether anyone is really using scripts that invoke createdb -D ...)
2004-06-18 23:47:24 +02:00
Specifies the name of the database to be created. The name must be
unique among all <productname>PostgreSQL</productname> databases in this cluster.
Assorted reference page updates
2002-10-12 01:03:48 +02:00
The default is to create a database with the same name as the
current system user.
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>
<varlistentry>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<term><replaceable class="parameter">description</replaceable></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>
Replace createdb's obsolete --location switch with --tablespace. I kept the same abbreviated letter -D, in hopes of maintaining some modicum of backwards compatibility (though it's doubtful whether anyone is really using scripts that invoke createdb -D ...)
2004-06-18 23:47:24 +02:00
Specifies a comment to be associated with the newly created
database.
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>
<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>-D <replaceable class="parameter">tablespace</replaceable></option></term>
<term><option>--tablespace=<replaceable class="parameter">tablespace</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>
Remove double-quoting of table names in clusterdb. BACKWARD COMPABILITY BREAKAGE. Remove double-quoting of index/table names in reindexdb. BACKWARD COMPABILITY BREAKAGE. Document thate user/database names are preserved with double-quoting by command-line tools like vacuumdb.
2011-09-10 22:39:02 +02:00
Specifies the default tablespace for the database. (This name
is processed as a double-quoted identifier.)
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>
<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>-e</option></term>
<term><option>--echo</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
Echo the commands that <application>createdb</application> generates
Replace createdb's obsolete --location switch with --tablespace. I kept the same abbreviated letter -D, in hopes of maintaining some modicum of backwards compatibility (though it's doubtful whether anyone is really using scripts that invoke createdb -D ...)
2004-06-18 23:47:24 +02:00
and sends to the server.
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>
Put options in more alphabetical order
2011-05-10 21:37:22 +02: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>-E <replaceable class="parameter">encoding</replaceable></option></term>
<term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
Put options in more alphabetical order
2011-05-10 21:37:22 +02:00
<listitem>
<para>
Specifies the character encoding scheme to be used in this
database. The character sets supported by the
<productname>PostgreSQL</productname> server are described in
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
<xref linkend="multibyte-charset-supported"/>.
Put options in more alphabetical order
2011-05-10 21:37:22 +02:00
</para>
</listitem>
</varlistentry>
Add a --locale switch to createdb, to ease the creation of databases with different locales. This is just syntactical sweetener over --lc-collate and --lc-ctype. Per discussion. While at it, properly document --lc-ctype and --lc-collate in SGML docs, which apparently were forgotten (or purposefully ommited?) when they were created.
2008-11-10 17:25:41 +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>-l <replaceable class="parameter">locale</replaceable></option></term>
<term><option>--locale=<replaceable class="parameter">locale</replaceable></option></term>
Add a --locale switch to createdb, to ease the creation of databases with different locales. This is just syntactical sweetener over --lc-collate and --lc-ctype. Per discussion. While at it, properly document --lc-ctype and --lc-collate in SGML docs, which apparently were forgotten (or purposefully ommited?) when they were created.
2008-11-10 17:25:41 +01:00
<listitem>
<para>
Specifies the locale to be used in this database. This is equivalent
CREATE DATABASE: make LOCALE apply to all collation providers. For CREATE DATABASE, make LOCALE parameter apply regardless of the provider used. Also affects initdb and createdb --locale arguments. Previously, LOCALE (and --locale) only affected the database default collation when using the libc provider. Discussion: https://postgr.es/m/1a63084d-221e-4075-619e-6b3e590f673e@enterprisedb.com Reviewed-by: Peter Eisentraut
2023-06-16 19:27:32 +02:00
to specifying <option>--lc-collate</option>,
<option>--lc-ctype</option>, and <option>--icu-locale</option> to the
same value. Some locales are only valid for ICU and must be set with
<option>--icu-locale</option>.
Add a --locale switch to createdb, to ease the creation of databases with different locales. This is just syntactical sweetener over --lc-collate and --lc-ctype. Per discussion. While at it, properly document --lc-ctype and --lc-collate in SGML docs, which apparently were forgotten (or purposefully ommited?) when they were created.
2008-11-10 17:25:41 +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>--lc-collate=<replaceable class="parameter">locale</replaceable></option></term>
Add a --locale switch to createdb, to ease the creation of databases with different locales. This is just syntactical sweetener over --lc-collate and --lc-ctype. Per discussion. While at it, properly document --lc-ctype and --lc-collate in SGML docs, which apparently were forgotten (or purposefully ommited?) when they were created.
2008-11-10 17:25:41 +01:00
<listitem>
<para>
Specifies the LC_COLLATE setting to be used in this database.
</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>--lc-ctype=<replaceable class="parameter">locale</replaceable></option></term>
Add a --locale switch to createdb, to ease the creation of databases with different locales. This is just syntactical sweetener over --lc-collate and --lc-ctype. Per discussion. While at it, properly document --lc-ctype and --lc-collate in SGML docs, which apparently were forgotten (or purposefully ommited?) when they were created.
2008-11-10 17:25:41 +01:00
<listitem>
<para>
Specifies the LC_CTYPE setting to be used in this database.
</para>
</listitem>
</varlistentry>
Fix documentation oversights from 2d819a08a1.
2024-03-19 01:13:18 +01:00
<varlistentry>
<term><option>--builtin-locale=<replaceable class="parameter">locale</replaceable></option></term>
<listitem>
<para>
Specifies the locale name when the builtin provider is used. Locale support
is described in <xref linkend="locale"/>.
</para>
</listitem>
</varlistentry>
Add option to use ICU as global locale provider This adds the option to use ICU as the default locale provider for either the whole cluster or a database. New options for initdb, createdb, and CREATE DATABASE are used to select this. Since some (legacy) code still uses the libc locale facilities directly, we still need to set the libc global locale settings even if ICU is otherwise selected. So pg_database now has three locale-related fields: the existing datcollate and datctype, which are always set, and a new daticulocale, which is only set if ICU is selected. A similar change is made in pg_collation for consistency, but in that case, only the libc-related fields or the ICU-related field is set, never both. Reviewed-by: Julien Rouhaud <rjuju123@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/5e756dd6-0e91-d778-96fd-b1bcb06c161a%402ndquadrant.com
2022-03-17 11:11:21 +01:00
<varlistentry>
<term><option>--icu-locale=<replaceable class="parameter">locale</replaceable></option></term>
<listitem>
<para>
Specifies the ICU locale ID to be used in this database, if the
ICU locale provider is selected.
</para>
</listitem>
</varlistentry>
Allow tailoring of ICU locales with custom rules This exposes the ICU facility to add custom collation rules to a standard collation. New options are added to CREATE COLLATION, CREATE DATABASE, createdb, and initdb to set the rules. Reviewed-by: Laurenz Albe <laurenz.albe@cybertec.at> Reviewed-by: Daniel Verite <daniel@manitou-mail.org> Discussion: https://www.postgresql.org/message-id/flat/821c71a4-6ef0-d366-9acf-bb8e367f739f@enterprisedb.com
2023-03-08 16:35:42 +01:00
<varlistentry>
<term><option>--icu-rules=<replaceable class="parameter">rules</replaceable></option></term>
<listitem>
<para>
Specifies additional collation rules to customize the behavior of the
default collation of this database. This is supported for ICU only.
</para>
</listitem>
</varlistentry>
Add option to use ICU as global locale provider This adds the option to use ICU as the default locale provider for either the whole cluster or a database. New options for initdb, createdb, and CREATE DATABASE are used to select this. Since some (legacy) code still uses the libc locale facilities directly, we still need to set the libc global locale settings even if ICU is otherwise selected. So pg_database now has three locale-related fields: the existing datcollate and datctype, which are always set, and a new daticulocale, which is only set if ICU is selected. A similar change is made in pg_collation for consistency, but in that case, only the libc-related fields or the ICU-related field is set, never both. Reviewed-by: Julien Rouhaud <rjuju123@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/5e756dd6-0e91-d778-96fd-b1bcb06c161a%402ndquadrant.com
2022-03-17 11:11:21 +01:00
<varlistentry>
Introduce "builtin" collation provider. New provider for collations, like "libc" or "icu", but without any external dependency. Initially, the only locale supported by the builtin provider is "C", which is identical to the libc provider's "C" locale. The libc provider's "C" locale has always been treated as a special case that uses an internal implementation, without using libc at all -- so the new builtin provider uses the same implementation. The builtin provider's locale is independent of the server environment variables LC_COLLATE and LC_CTYPE. Using the builtin provider, the database collation locale can be "C" while LC_COLLATE and LC_CTYPE are set to "en_US", which is impossible with the libc provider. By offering a new builtin provider, it clarifies that the semantics of a collation using this provider will never depend on libc, and makes it easier to document the behavior. Discussion: https://postgr.es/m/ab925f69-5f9d-f85e-b87c-bd2a44798659@joeconway.com Discussion: https://postgr.es/m/dd9261f4-7a98-4565-93ec-336c1c110d90@manitou-mail.org Discussion: https://postgr.es/m/ff4c2f2f9c8fc7ca27c1c24ae37ecaeaeaff6b53.camel%40j-davis.com Reviewed-by: Daniel Vérité, Peter Eisentraut, Jeremy Schneider
2024-03-14 07:33:44 +01:00
<term><option>--locale-provider={<literal>builtin</literal>|<literal>libc</literal>|<literal>icu</literal>}</option></term>
Add option to use ICU as global locale provider This adds the option to use ICU as the default locale provider for either the whole cluster or a database. New options for initdb, createdb, and CREATE DATABASE are used to select this. Since some (legacy) code still uses the libc locale facilities directly, we still need to set the libc global locale settings even if ICU is otherwise selected. So pg_database now has three locale-related fields: the existing datcollate and datctype, which are always set, and a new daticulocale, which is only set if ICU is selected. A similar change is made in pg_collation for consistency, but in that case, only the libc-related fields or the ICU-related field is set, never both. Reviewed-by: Julien Rouhaud <rjuju123@gmail.com> Discussion: https://www.postgresql.org/message-id/flat/5e756dd6-0e91-d778-96fd-b1bcb06c161a%402ndquadrant.com
2022-03-17 11:11:21 +01:00
<listitem>
<para>
Specifies the locale provider for the database's default collation.
</para>
</listitem>
</varlistentry>
Add -O/--owner switch to createdb script, in support of new OWNER option for CREATE DATABASE.
2002-02-25 00:27:58 +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>-O <replaceable class="parameter">owner</replaceable></option></term>
<term><option>--owner=<replaceable class="parameter">owner</replaceable></option></term>
Add -O/--owner switch to createdb script, in support of new OWNER option for CREATE DATABASE.
2002-02-25 00:27:58 +01:00
<listitem>
<para>
Replace createdb's obsolete --location switch with --tablespace. I kept the same abbreviated letter -D, in hopes of maintaining some modicum of backwards compatibility (though it's doubtful whether anyone is really using scripts that invoke createdb -D ...)
2004-06-18 23:47:24 +02:00
Specifies the database user who will own the new database.
Remove double-quoting of table names in clusterdb. BACKWARD COMPABILITY BREAKAGE. Remove double-quoting of index/table names in reindexdb. BACKWARD COMPABILITY BREAKAGE. Document thate user/database names are preserved with double-quoting by command-line tools like vacuumdb.
2011-09-10 22:39:02 +02:00
(This name is processed as a double-quoted identifier.)
Add -O/--owner switch to createdb script, in support of new OWNER option for CREATE DATABASE.
2002-02-25 00:27:58 +01:00
</para>
</listitem>
</varlistentry>
Add new block-by-block strategy for CREATE DATABASE. Because this strategy logs changes on a block-by-block basis, it avoids the need to checkpoint before and after the operation. However, because it logs each changed block individually, it might generate a lot of extra write-ahead logging if the template database is large. Therefore, the older strategy remains available via a new STRATEGY parameter to CREATE DATABASE, and a corresponding --strategy option to createdb. Somewhat controversially, this patch assembles the list of relations to be copied to the new database by reading the pg_class relation of the template database. Cross-database access like this isn't normally possible, but it can be made to work here because there can't be any connections to the database being copied, nor can it contain any in-doubt transactions. Even so, we have to use lower-level interfaces than normal, since the table scan and relcache interfaces will not work for a database to which we're not connected. The advantage of this approach is that we do not need to rely on the filesystem to determine what ought to be copied, but instead on PostgreSQL's own knowledge of the database structure. This avoids, for example, copying stray files that happen to be located in the source database directory. Dilip Kumar, with a fairly large number of cosmetic changes by me. Reviewed and tested by Ashutosh Sharma, Andres Freund, John Naylor, Greg Nancarrow, Neha Sharma. Additional feedback from Bruce Momjian, Heikki Linnakangas, Julien Rouhaud, Adam Brusselback, Kyotaro Horiguchi, Tomas Vondra, Andrew Dunstan, Álvaro Herrera, and others. Discussion: http://postgr.es/m/CA+TgmoYtcdxBjLh31DLxUXHxFVMPGzrU5_T=CYCvRyFHywSBUQ@mail.gmail.com
2022-03-29 17:31:43 +02:00
<varlistentry>
createdb: Correct parameter name in SGML docs Commit 9c08aea6a309 introduced -S/--strategy option, but forgot to rename the parameter when copying the -T/--template bit.
2024-04-20 18:54:09 +02:00
<term><option>-S <replaceable class="parameter">strategy</replaceable></option></term>
Add new block-by-block strategy for CREATE DATABASE. Because this strategy logs changes on a block-by-block basis, it avoids the need to checkpoint before and after the operation. However, because it logs each changed block individually, it might generate a lot of extra write-ahead logging if the template database is large. Therefore, the older strategy remains available via a new STRATEGY parameter to CREATE DATABASE, and a corresponding --strategy option to createdb. Somewhat controversially, this patch assembles the list of relations to be copied to the new database by reading the pg_class relation of the template database. Cross-database access like this isn't normally possible, but it can be made to work here because there can't be any connections to the database being copied, nor can it contain any in-doubt transactions. Even so, we have to use lower-level interfaces than normal, since the table scan and relcache interfaces will not work for a database to which we're not connected. The advantage of this approach is that we do not need to rely on the filesystem to determine what ought to be copied, but instead on PostgreSQL's own knowledge of the database structure. This avoids, for example, copying stray files that happen to be located in the source database directory. Dilip Kumar, with a fairly large number of cosmetic changes by me. Reviewed and tested by Ashutosh Sharma, Andres Freund, John Naylor, Greg Nancarrow, Neha Sharma. Additional feedback from Bruce Momjian, Heikki Linnakangas, Julien Rouhaud, Adam Brusselback, Kyotaro Horiguchi, Tomas Vondra, Andrew Dunstan, Álvaro Herrera, and others. Discussion: http://postgr.es/m/CA+TgmoYtcdxBjLh31DLxUXHxFVMPGzrU5_T=CYCvRyFHywSBUQ@mail.gmail.com
2022-03-29 17:31:43 +02:00
<term><option>--strategy=<replaceable class="parameter">strategy</replaceable></option></term>
<listitem>
<para>
Specifies the database creation strategy. See
<xref linkend="create-database-strategy" /> for more details.
</para>
</listitem>
</varlistentry>
Add --template option to createdb script to allow access to WITH TEMPLATE option of CREATE DATABASE. In pg_regress, create regression database from template0 to ensure that any installation-local cruft in template1 will not mess up the tests.
2001-02-18 18:53:55 +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>-T <replaceable class="parameter">template</replaceable></option></term>
<term><option>--template=<replaceable class="parameter">template</replaceable></option></term>
Add --template option to createdb script to allow access to WITH TEMPLATE option of CREATE DATABASE. In pg_regress, create regression database from template0 to ensure that any installation-local cruft in template1 will not mess up the tests.
2001-02-18 18:53:55 +01:00
<listitem>
<para>
Remove double-quoting of table names in clusterdb. BACKWARD COMPABILITY BREAKAGE. Remove double-quoting of index/table names in reindexdb. BACKWARD COMPABILITY BREAKAGE. Document thate user/database names are preserved with double-quoting by command-line tools like vacuumdb.
2011-09-10 22:39:02 +02:00
Specifies the template database from which to build this
database. (This name is processed as a double-quoted identifier.)
Add --template option to createdb script to allow access to WITH TEMPLATE option of CREATE DATABASE. In pg_regress, create regression database from template0 to ensure that any installation-local cruft in template1 will not mess up the tests.
2001-02-18 18:53:55 +01:00
</para>
</listitem>
</varlistentry>
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>createdb</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>createdb</application> command line
arguments, and exit.
</para>
</listitem>
</varlistentry>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
</variablelist>
</para>
Add --template option to createdb script to allow access to WITH TEMPLATE option of CREATE DATABASE. In pg_regress, create regression database from template0 to ensure that any installation-local cruft in template1 will not mess up the tests.
2001-02-18 18:53:55 +01:00
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<para>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
The options <option>-D</option>, <option>-l</option>, <option>-E</option>,
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<option>-O</option>, and
<option>-T</option> correspond to options of the underlying
Improve <xref> vs. <command> formatting in the documentation SQL commands are generally marked up as <command>, except when a link to a reference page is used using <xref>. But the latter doesn't create monospace markup, so this looks strange especially when a paragraph contains a mix of links and non-links. We considered putting <command> in the <refentrytitle> on the target side, but that creates some formatting side effects elsewhere. Generally, it seems safer to solve this on the link source side. We can't put the <xref> inside the <command>; the DTD doesn't allow this. DocBook 5 would allow the <command> to have the linkend attribute itself, but we are not there yet. So to solve this for now, convert the <xref>s to <link> plus <command>. This gives the correct look and also gives some more flexibility what we can put into the link text (e.g., subcommands or other clauses). In the future, these could then be converted to DocBook 5 style. I haven't converted absolutely all xrefs to SQL command reference pages, only those where we care about the appearance of the link text or where it was otherwise appropriate to make the appearance match a bit better. Also in some cases, the links where repetitive, so in those cases the links where just removed and replaced by a plain <command>. In cases where we just want the link and don't specifically care about the generated link text (typically phrased "for further information see <xref ...>") the xref is kept. Reported-by: Dagfinn Ilmari Mannsåker <ilmari@ilmari.org> Discussion: https://www.postgresql.org/message-id/flat/87o8pco34z.fsf@wibble.ilmari.org
2020-10-03 16:16:51 +02:00
SQL command <link linkend="sql-createdatabase"><command>CREATE DATABASE</command></link>; see there for more information
Assorted reference page updates
2002-10-12 01:03:48 +02:00
about them.
</para>
<para>
<application>createdb</application> also accepts the following
command-line arguments for connection parameters:
<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
<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>-h <replaceable class="parameter">host</replaceable></option></term>
<term><option>--host=<replaceable class="parameter">host</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>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Specifies the host name of the machine on which the
server is running. If the value begins with a slash, it is used
Replace createdb's obsolete --location switch with --tablespace. I kept the same abbreviated letter -D, in hopes of maintaining some modicum of backwards compatibility (though it's doubtful whether anyone is really using scripts that invoke createdb -D ...)
2004-06-18 23:47:24 +02:00
as the directory for the Unix domain socket.
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>
<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>-p <replaceable class="parameter">port</replaceable></option></term>
<term><option>--port=<replaceable class="parameter">port</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>
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
Specifies the TCP port or the local Unix domain socket file
Replace createdb's obsolete --location switch with --tablespace. I kept the same abbreviated letter -D, in hopes of maintaining some modicum of backwards compatibility (though it's doubtful whether anyone is really using scripts that invoke createdb -D ...)
2004-06-18 23:47:24 +02:00
extension on which the server is listening for connections.
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>
<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>-U <replaceable class="parameter">username</replaceable></option></term>
<term><option>--username=<replaceable class="parameter">username</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>
Make documentation of -W options more accurate and uniform.
2007-12-11 20:57:32 +01:00
User name to connect as.
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 a -w/--no-password option that prevents all password prompts to all programs that have a -W/--password option. In passing, remove the ancient PSQL_ALWAYS_GET_PASSWORDS compile option.
2009-02-26 17:02:39 +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>-w</option></term>
<term><option>--no-password</option></term>
Add a -w/--no-password option that prevents all password prompts to all programs that have a -W/--password option. In passing, remove the ancient PSQL_ALWAYS_GET_PASSWORDS compile option.
2009-02-26 17:02:39 +01:00
<listitem>
<para>
Never issue a password prompt. If the server requires
password authentication and a password is not available by
other means such as a <filename>.pgpass</filename> file, the
connection attempt will fail. This option can be useful in
batch jobs and scripts where no user is present to enter a
password.
</para>
</listitem>
</varlistentry>
Assorted reference page updates
2002-10-12 01:03:48 +02: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>-W</option></term>
<term><option>--password</option></term>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
<listitem>
<para>
Make documentation of -W options more accurate and uniform.
2007-12-11 20:57:32 +01:00
Force <application>createdb</application> to prompt for a
Remove useless whitespace at end of lines
2010-11-23 21:27:50 +01:00
password before connecting to a database.
Make documentation of -W options more accurate and uniform.
2007-12-11 20:57:32 +01:00
</para>
<para>
This option is never essential, since
<application>createdb</application> will automatically prompt
for a password if the server demands password authentication.
However, <application>createdb</application> will waste a
connection attempt finding out that the server wants a password.
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
In some cases it is worth typing <option>-W</option> to avoid the extra
Make documentation of -W options more accurate and uniform.
2007-12-11 20:57:32 +01:00
connection attempt.
Assorted reference page updates
2002-10-12 01:03:48 +02:00
</para>
</listitem>
</varlistentry>
Make command-line tools smarter about finding a DB to connect to. If unable to connect to "postgres", try "template1". This allows things to work more smoothly in the case where the postgres database has been dropped. And just in case that's not good enough, also allow the user to specify a maintenance database to be used for the initial connection, to cover the case where neither postgres nor template1 is suitable.
2011-12-06 14:48:15 +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>--maintenance-db=<replaceable class="parameter">dbname</replaceable></option></term>
Make command-line tools smarter about finding a DB to connect to. If unable to connect to "postgres", try "template1". This allows things to work more smoothly in the case where the postgres database has been dropped. And just in case that's not good enough, also allow the user to specify a maintenance database to be used for the initial connection, to cover the case where neither postgres nor template1 is suitable.
2011-12-06 14:48:15 +01:00
<listitem>
<para>
Specifies the name of the database to connect to when creating the
new database. If not specified, the <literal>postgres</literal>
database will be used; if that does not exist (or if it is the name
of the new database being created), <literal>template1</literal> will
be used.
Fix connection string handling in src/bin/scripts/ programs. When told to process all databases, clusterdb, reindexdb, and vacuumdb would reconnect by replacing their --maintenance-db parameter with the name of the target database. If that parameter is a connstring (which has been allowed for a long time, though we failed to document that before this patch), we'd lose any other options it might specify, for example SSL or GSS parameters, possibly resulting in failure to connect. Thus, this is the same bug as commit a45bc8a4f fixed in pg_dump and pg_restore. We can fix it in the same way, by using libpq's rules for handling multiple "dbname" parameters to add the target database name separately. I chose to apply the same refactoring approach as in that patch, with a struct to handle the command line parameters that need to be passed through to connectDatabase. (Maybe someday we can unify the very similar functions here and in pg_dump/pg_restore.) Per Peter Eisentraut's comments on bug #16604. Back-patch to all supported branches. Discussion: https://postgr.es/m/16604-933f4b8791227b15@postgresql.org
2020-10-20 01:03:46 +02:00
This can be a <link linkend="libpq-connstring">connection
string</link>. If so, connection string parameters will override any
conflicting command line options.
Make command-line tools smarter about finding a DB to connect to. If unable to connect to "postgres", try "template1". This allows things to work more smoothly in the case where the postgres database has been dropped. And just in case that's not good enough, also allow the user to specify a maintenance database to be used for the initial connection, to cover the case where neither postgres nor template1 is suitable.
2011-12-06 14:48:15 +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
</variablelist>
New scripts for create/drop user/db from Peter Eisentraut
1999-12-04 05:53:22 +01:00
</para>
Assorted reference page updates
2002-10-12 01:03:48 +02:00
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
</refsect1>
<refsect1>
<title>Environment</title>
New scripts for create/drop user/db from Peter Eisentraut
1999-12-04 05:53:22 +01:00
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
<variablelist>
Make sure all clients have the same understanding of default user name and database. In particular, make script wrappers understand the PGDATABASE environment variable.
2002-08-10 18:57:32 +02:00
<varlistentry>
<term><envar>PGDATABASE</envar></term>
<listitem>
<para>
If set, the name of the database to create, unless overridden on
the command line.
</para>
</listitem>
</varlistentry>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
<varlistentry>
<term><envar>PGHOST</envar></term>
<term><envar>PGPORT</envar></term>
<term><envar>PGUSER</envar></term>
<listitem>
<para>
Default connection parameters. <envar>PGUSER</envar> also
determines the name of the database to create, if it is not
Make sure all clients have the same understanding of default user name and database. In particular, make script wrappers understand the PGDATABASE environment variable.
2002-08-10 18:57:32 +02:00
specified on the command line or by <envar>PGDATABASE</envar>.
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
</para>
</listitem>
</varlistentry>
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>
Doc: fix some description of environment variables with frontend tools This addresses a couple of issues in the documentation: - Description of PG_COLOR was missing for some tools (pg_archivecleanup and pg_test_fsync), while the other descriptions had grammar mistakes. - pgbench supports more environment variables: PGUSER, PGHOST and PGPORT. - vacuumlo, oid2name and pgbench support coloring (HEAD only) Author: Michael Paquier Reviewed-by: Fabien Coelho, Daniel Gustafsson, Juan José Santamaría Flecha Discussion: https://postgr.es/m/20200304075418.GJ2593@paquier.xyz Backpatch-through: 12
2020-03-09 02:53:22 +01:00
Specifies whether to use color in diagnostic messages. Possible values
are <literal>always</literal>, <literal>auto</literal> and
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
<literal>never</literal>.
</para>
</listitem>
</varlistentry>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +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>
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>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
Mop-up for error-message updates in documentation.
2003-09-13 01:04:46 +02:00
<refsect1>
<title>Diagnostics</title>
<para>
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 case of difficulty, see <xref linkend="sql-createdatabase"/>
and <xref linkend="app-psql"/> for
Mop-up for error-message updates in documentation.
2003-09-13 01:04:46 +02:00
discussions of potential problems and error messages.
The database server must be running at the
targeted host. Also, any default connection settings and environment
variables used by the <application>libpq</application> front-end
library will apply.
</para>
</refsect1>
<refsect1>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
<title>Examples</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
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<para>
To create the database <literal>demo</literal> using the default
database server:
<screen>
<prompt>$ </prompt><userinput>createdb demo</userinput>
</screen>
</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
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<para>
To create the database <literal>demo</literal> using the
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
server on host <literal>eden</literal>, port 5000, using the
doc: improve createdb example The previous example could error out due to encoding mismatches; use -T/template instead. Reported-by: Jason O'Donnell
2017-03-21 02:23:56 +01:00
<literal>template0</literal> template database, here is the
command-line command and the underlying SQL command:
Markup enhancements, some factual corrections.
2000-11-12 00:01:45 +01:00
<screen>
doc: improve createdb example The previous example could error out due to encoding mismatches; use -T/template instead. Reported-by: Jason O'Donnell
2017-03-21 02:23:56 +01:00
<prompt>$ </prompt><userinput>createdb -p 5000 -h eden -T template0 -e demo</userinput>
<computeroutput>CREATE DATABASE demo TEMPLATE template0;</computeroutput>
Fix a whitespace issue with the man pages There is what may actually be a mistake in our markup. The problem is in a situation like <para> <command>FOO</command> is ... there is strictly speaking a line break before "FOO". In the HTML output, this does not appear to be a problem, but in the man page output, this shows up, so you get double blank lines at odd places. So far, we have attempted to work around this with an XSL hack, but that causes other problems, such as creating run-ins in places like <acronym>SQL</acronym> <command>COPY</command> So fix the problem properly by removing the extra whitespace. I only fixed the problems that affect the man page output, not all the places.
2011-08-07 09:49:45 +02:00
</screen></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
</refsect1>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
<refsect1>
<title>See Also</title>
<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-dropdb"/></member>
<member><xref linkend="sql-createdatabase"/></member>
Structure reference pages consistently. Document that structure. Add information about environment variables.
2002-07-28 17:22:21 +02:00
</simplelist>
</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
</refentry>