mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-09-30 19:31:14 +02:00
Improve documentation around parameter-setting and ALTER SYSTEM.
The ALTER SYSTEM ref page hadn't been held to a very high standard, nor
was the feature well integrated into section 18.1 (parameter setting).
Also, though commit 4c4654afe
had improved the structure of 18.1, it also
introduced a lot of poor wording, imprecision, and outright falsehoods.
Try to clean that up.
This commit is contained in:
parent
0923b01e3e
commit
af06aa822d
@ -23,15 +23,16 @@
|
|||||||
|
|
||||||
<para>
|
<para>
|
||||||
All parameter names are case-insensitive. Every parameter takes a
|
All parameter names are case-insensitive. Every parameter takes a
|
||||||
value of one of five types: boolean, integer, floating point,
|
value of one of five types: boolean, string, integer, floating point,
|
||||||
string, or enum.
|
or enumerated (enum). The type determines the syntax for setting the
|
||||||
|
parameter:
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Boolean:</emphasis> Values can be written as
|
<emphasis>Boolean:</emphasis>
|
||||||
|
Values can be written as
|
||||||
<literal>on</literal>,
|
<literal>on</literal>,
|
||||||
<literal>off</literal>,
|
<literal>off</literal>,
|
||||||
<literal>true</literal>,
|
<literal>true</literal>,
|
||||||
@ -40,37 +41,42 @@
|
|||||||
<literal>no</literal>,
|
<literal>no</literal>,
|
||||||
<literal>1</literal>,
|
<literal>1</literal>,
|
||||||
<literal>0</literal>
|
<literal>0</literal>
|
||||||
(all case-insensitive) or any unambiguous prefix of these.
|
(all case-insensitive) or any unambiguous prefix of one of these.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>String:</emphasis> Enclose the value in
|
<emphasis>String:</emphasis>
|
||||||
single-quotes. Values are case-insensitive. If multiple values
|
In general, enclose the value in single quotes, doubling any single
|
||||||
are allowed, separate them with commas.
|
quotes within the value. Quotes can usually be omitted if the value
|
||||||
|
is a simple number or identifier, however.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Numeric (integer and floating point):</emphasis> Do
|
<emphasis>Numeric (integer and floating point):</emphasis>
|
||||||
not use single-quotes (unless otherwise required) or thousand
|
A decimal point is permitted only for floating-point parameters.
|
||||||
separators.
|
Do not use thousands separators. Quotes are not required.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis>Numeric or String with Unit (Memory &
|
<emphasis>Numeric with Unit:</emphasis>
|
||||||
Time):</emphasis> These have an implicit unit, which is
|
Some numeric parameters have an implicit unit, because they describe
|
||||||
either kilobytes, blocks (typically eight kilobytes),
|
quantities of memory or time. The unit might be kilobytes, blocks
|
||||||
milliseconds, seconds, or minutes. A unadorned numeric
|
(typically eight kilobytes), milliseconds, seconds, or minutes.
|
||||||
value will use the default, which can be found by referencing
|
An unadorned numeric value for one of these settings will use the
|
||||||
<structname>pg_settings</>.<structfield>unit</>. For convenience,
|
setting's default unit, which can be learned from
|
||||||
a different unit can also be specified explicitly via a string
|
<structname>pg_settings</>.<structfield>unit</>.
|
||||||
value. It is case-sensitive and may include whitespace between
|
For convenience, settings can be given with a unit specified explicitly,
|
||||||
the value and the unit.
|
for example <literal>'120 ms'</> for a time value, and they will be
|
||||||
|
converted to whatever the parameter's actual unit is. Note that the
|
||||||
|
value must be written as a string (with quotes) to use this feature.
|
||||||
|
The unit name is case-sensitive, and there can be whitespace between
|
||||||
|
the numeric value and the unit.
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
@ -95,13 +101,11 @@
|
|||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
<emphasis><quote>enum</>:</emphasis> These are specified
|
<emphasis>Enumerated:</emphasis>
|
||||||
in the same way as string parameters, but are restricted
|
Enumerated-type parameters are written in the same way as string
|
||||||
to a limited set of values that can be queried from
|
parameters, but are restricted to have one of a limited set of
|
||||||
<structname>pg_settings</>.<structfield>enumvals</>:
|
values. The values allowable for such a parameter can be found from
|
||||||
<programlisting>
|
<structname>pg_settings</>.<structfield>enumvals</>.
|
||||||
SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL;
|
|
||||||
</programlisting>
|
|
||||||
Enum parameter values are case-insensitive.
|
Enum parameter values are case-insensitive.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
@ -109,13 +113,13 @@ SELECT name, setting, enumvals FROM pg_settings WHERE enumvals IS NOT NULL;
|
|||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="config-setting-configuration-file">
|
<sect2 id="config-setting-configuration-file">
|
||||||
<title>Parameter Interaction via Configuration File</title>
|
<title>Parameter Interaction via the Configuration File</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
The primary way to set these parameters is to edit the file
|
The most fundamental way to set these parameters is to edit the file
|
||||||
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
|
<filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
|
||||||
which is normally kept in the data directory. (A default copy is
|
which is normally kept in the data directory. A default copy is
|
||||||
installed when the database cluster directory is initialized.)
|
installed when the database cluster directory is initialized.
|
||||||
An example of what this file might look like is:
|
An example of what this file might look like is:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
# This is a comment
|
# This is a comment
|
||||||
@ -125,18 +129,19 @@ search_path = '"$user", public'
|
|||||||
shared_buffers = 128MB
|
shared_buffers = 128MB
|
||||||
</programlisting>
|
</programlisting>
|
||||||
One parameter is specified per line. The equal sign between name and
|
One parameter is specified per line. The equal sign between name and
|
||||||
value is optional. Whitespace is insignificant and blank lines are
|
value is optional. Whitespace is insignificant (except within a quoted
|
||||||
|
parameter value) and blank lines are
|
||||||
ignored. Hash marks (<literal>#</literal>) designate the remainder
|
ignored. Hash marks (<literal>#</literal>) designate the remainder
|
||||||
of the line as a comment. Parameter values that are not simple
|
of the line as a comment. Parameter values that are not simple
|
||||||
identifiers or numbers must be single-quoted. To embed a single
|
identifiers or numbers must be single-quoted. To embed a single
|
||||||
quote in a parameter value write either two quotes (preferred)
|
quote in a parameter value, write either two quotes (preferred)
|
||||||
or backslash-quote.
|
or backslash-quote.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Parameters set in this way provide default values for the cluster.
|
Parameters set in this way provide default values for the cluster.
|
||||||
The setting seen by active sessions will be this value unless
|
The settings seen by active sessions will be these values unless they
|
||||||
it is overridden. The following sections describe ways in which the
|
are overridden. The following sections describe ways in which the
|
||||||
administrator or user can override these defaults.
|
administrator or user can override these defaults.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
@ -145,61 +150,75 @@ shared_buffers = 128MB
|
|||||||
<primary>SIGHUP</primary>
|
<primary>SIGHUP</primary>
|
||||||
</indexterm>
|
</indexterm>
|
||||||
The configuration file is reread whenever the main server process
|
The configuration file is reread whenever the main server process
|
||||||
receives a <systemitem>SIGHUP</> signal; this is most easily done by
|
receives a <systemitem>SIGHUP</> signal; this signal is most easily
|
||||||
running <literal>pg_ctl reload</> from the command-line or by calling
|
sent by running <literal>pg_ctl reload</> from the command line or by
|
||||||
the SQL function <function>pg_reload_conf()</function>. The main
|
calling the SQL function <function>pg_reload_conf()</function>. The main
|
||||||
server process also propagates this signal to all currently running
|
server process also propagates this signal to all currently running
|
||||||
server processes so that existing sessions also get the new value
|
server processes, so that existing sessions also adopt the new values
|
||||||
when they complete their transactions. Alternatively, you can
|
(this will happen after they complete any currently-executing client
|
||||||
|
command). Alternatively, you can
|
||||||
send the signal to a single server process directly. Some parameters
|
send the signal to a single server process directly. Some parameters
|
||||||
can only be set at server start; any changes to their entries in the
|
can only be set at server start; any changes to their entries in the
|
||||||
configuration file will be ignored until the server is restarted.
|
configuration file will be ignored until the server is restarted.
|
||||||
Invalid parameter settings in the configuration file are likewise
|
Invalid parameter settings in the configuration file are likewise
|
||||||
ignored (but logged) during <systemitem>SIGHUP</> processing.
|
ignored (but logged) during <systemitem>SIGHUP</> processing.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
In addition to <filename>postgresql.conf</>,
|
||||||
|
a <productname>PostgreSQL</productname> data directory contains a file
|
||||||
|
<filename>postgresql.auto.conf</><indexterm><primary>postgresql.auto.conf</></>,
|
||||||
|
which has the same format as <filename>postgresql.conf</> but should
|
||||||
|
never be edited manually. This file holds settings provided through
|
||||||
|
the <xref linkend="SQL-ALTERSYSTEM"> command. This file is automatically
|
||||||
|
read whenever <filename>postgresql.conf</> is, and its settings take
|
||||||
|
effect in the same way. Settings in <filename>postgresql.auto.conf</>
|
||||||
|
override those in <filename>postgresql.conf</>.
|
||||||
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="config-setting-sql-command-interaction">
|
<sect2 id="config-setting-sql-command-interaction">
|
||||||
<title>Parameter Interaction via SQL</title>
|
<title>Parameter Interaction via SQL</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<productname>PostgreSQL</productname> provides three SQL
|
<productname>PostgreSQL</productname> provides three SQL
|
||||||
commands to establish configuration defaults that override those
|
commands to establish configuration defaults.
|
||||||
configured globally. The evaluation of these defaults occurs
|
The already-mentioned <xref linkend="SQL-ALTERSYSTEM"> command
|
||||||
at the beginning of a new session, upon the user issuing <xref
|
provides a SQL-accessible means of changing global defaults; it is
|
||||||
linkend="SQL-DISCARD">, or if the server forces the session to
|
functionally equivalent to editing <filename>postgresql.conf</>.
|
||||||
reload its configuration after a <systemitem>SIGHUP</systemitem>
|
In addition, there are two commands that allow setting of defaults
|
||||||
signal.
|
on a per-database or per-role basis:
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <xref linkend="SQL-ALTERSYSTEM"> command provides an
|
The <xref linkend="sql-alterdatabase"> command allows global
|
||||||
SQL-accessible means of changing global defaults.
|
settings to be overridden on a per-database basis.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <xref linkend="sql-alterdatabase"> command allows database
|
The <xref linkend="sql-alterrole"> command allows both global and
|
||||||
administrators to override global settings on a per-database basis.
|
per-database settings to be overridden with user-specific values.
|
||||||
</para>
|
|
||||||
</listitem>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>
|
|
||||||
The <xref linkend="sql-alterrole"> command allows database
|
|
||||||
administrators to override both global and per-database settings
|
|
||||||
with user-specific values.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Once a client connects to the database PostgreSQL provides
|
Values set with <command>ALTER DATABASE</> and <command>ALTER ROLE</>
|
||||||
two additional SQL commands to interact with session-local
|
are applied only when starting a fresh database session. They
|
||||||
configuration settings. Both of these commands have equivalent
|
override values obtained from the configuration files or server
|
||||||
system administration functions.
|
command line, and constitute defaults for the rest of the session.
|
||||||
|
Note that some settings cannot be changed after server start, and
|
||||||
|
so cannot be set with these commands (or the ones listed below).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
Once a client is connected to the database, <productname>PostgreSQL</>
|
||||||
|
provides two additional SQL commands (and equivalent functions) to
|
||||||
|
interact with session-local configuration settings:
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
@ -214,37 +233,37 @@ shared_buffers = 128MB
|
|||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
The <xref linkend="SQL-SET"> command allows modification of the
|
The <xref linkend="SQL-SET"> command allows modification of the
|
||||||
current value of some parameters. The corresponding function is
|
current value of those parameters that can be set locally to a
|
||||||
|
session; it has no effect on other sessions.
|
||||||
|
The corresponding function is
|
||||||
<function>set_config(setting_name, new_value, is_local)</function>.
|
<function>set_config(setting_name, new_value, is_local)</function>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Both <command>SELECT</> and <command>UPDATE</>
|
In addition, the system view <link
|
||||||
can be issued against the system view <link
|
linkend="view-pg-settings"><structname>pg_settings</></> can be
|
||||||
linkend="view-pg-settings"><structname>pg_settings</></> to view
|
used to view and change session-local values:
|
||||||
and change session-local values.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Querying this view is the same as <command>SHOW</> but provides
|
Querying this view is similar to using <command>SHOW ALL</> but
|
||||||
more detail, as well as allowing for joins against other relations
|
provides more detail. It is also more flexible, since it's possible
|
||||||
and the specification of filter criteria.
|
to specify filter conditions or join against other relations.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Using <xref linkend="SQL-UPDATE"> on this relation, specifically
|
Using <xref linkend="SQL-UPDATE"> on this view, specifically
|
||||||
updating the <structname>setting</> column, is the equivalent
|
updating the <structname>setting</> column, is the equivalent
|
||||||
of issuing SQL <command>SET</>, though all values must be
|
of issuing <command>SET</> commands. For example, the equivalent of
|
||||||
single-quoted. Note that the equivalent of
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
SET configuration_parameter TO DEFAULT;
|
SET configuration_parameter TO DEFAULT;
|
||||||
</>
|
</programlisting>
|
||||||
is:
|
is:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
|
UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter';
|
||||||
@ -256,7 +275,8 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter
|
|||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Parameter Interaction via Shell</title>
|
<title>Parameter Interaction via the Shell</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
In addition to setting global defaults or attaching
|
In addition to setting global defaults or attaching
|
||||||
overrides at the database or role level, you can pass settings to
|
overrides at the database or role level, you can pass settings to
|
||||||
@ -268,41 +288,38 @@ UPDATE pg_settings SET setting = reset_val WHERE name = 'configuration_parameter
|
|||||||
<itemizedlist>
|
<itemizedlist>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
On the <emphasis>server</emphasis>, command-line options can be
|
During server startup, parameter settings can be
|
||||||
passed to the <command>postgres</command> command directly via the
|
passed to the <command>postgres</command> command via the
|
||||||
<option>-c</> parameter.
|
<option>-c</> command-line parameter. For example,
|
||||||
<programlisting>
|
<programlisting>
|
||||||
postgres -c log_connections=yes -c log_destination='syslog'
|
postgres -c log_connections=yes -c log_destination='syslog'
|
||||||
</programlisting>
|
</programlisting>
|
||||||
Settings provided this way override those resolved globally (via
|
Settings provided in this way override those set via
|
||||||
<filename>postgresql.conf</> or <command>ALTER SYSTEM</>) but
|
<filename>postgresql.conf</> or <command>ALTER SYSTEM</>,
|
||||||
are otherwise treated as being global for the purpose of database
|
so they cannot be changed globally without restarting the server.
|
||||||
and role overrides.
|
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
On the <emphasis>libpq-client</emphasis>, command-line options can be
|
When starting a client session via <application>libpq</>,
|
||||||
|
parameter settings can be
|
||||||
specified using the <envar>PGOPTIONS</envar> environment variable.
|
specified using the <envar>PGOPTIONS</envar> environment variable.
|
||||||
When connecting to the server, the contents of this variable are
|
Settings established in this way constitute defaults for the life
|
||||||
sent to the server as if they were being executed via SQL <xref
|
of the session, but do not affect other sessions.
|
||||||
linkend="SQL-SET"> at the beginning of the session.
|
For historical reasons, the format of <envar>PGOPTIONS</envar> is
|
||||||
</para>
|
similar to that used when launching the <command>postgres</command>
|
||||||
|
command; specifically, the <option>-c</> flag must be specified.
|
||||||
<para>
|
For example,
|
||||||
However, the format of <envar>PGOPTIONS</envar> is similar to that
|
|
||||||
used when launching the <command>postgres</command> command.
|
|
||||||
Specifically, the <option>-c</> flag must be specified.
|
|
||||||
<programlisting>
|
<programlisting>
|
||||||
env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql
|
env PGOPTIONS="-c geqo=off -c statement_timeout=5min" psql
|
||||||
</programlisting>
|
</programlisting>
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Other clients and libraries might provide their own mechanisms,
|
Other clients and libraries might provide their own mechanisms,
|
||||||
via the shell or otherwise, that allow the user to alter session
|
via the shell or otherwise, that allow the user to alter session
|
||||||
settings without requiring the user to issue SQL commands.
|
settings without direct use of SQL commands.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</itemizedlist>
|
</itemizedlist>
|
||||||
@ -310,19 +327,26 @@ env PGOPTIONS="-c geqo=off -c statement_timeout='5 min'" psql
|
|||||||
</sect2>
|
</sect2>
|
||||||
|
|
||||||
<sect2 id="config-includes">
|
<sect2 id="config-includes">
|
||||||
<title>Configuration File Includes</title>
|
<title>Managing Configuration File Contents</title>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
<productname>PostgreSQL</> provides several features for breaking
|
||||||
|
down complex <filename>postgresql.conf</> files into sub-files.
|
||||||
|
These features are especially useful when managing multiple servers
|
||||||
|
with related, but not identical, configurations.
|
||||||
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<indexterm>
|
<indexterm>
|
||||||
<primary><literal>include</></primary>
|
<primary><literal>include</></primary>
|
||||||
<secondary>in configuration file</secondary>
|
<secondary>in configuration file</secondary>
|
||||||
</indexterm>
|
</indexterm>
|
||||||
In addition to parameter settings, the <filename>postgresql.conf</>
|
In addition to individual parameter settings,
|
||||||
file can contain <firstterm>include directives</>, which specify
|
the <filename>postgresql.conf</> file can contain <firstterm>include
|
||||||
another file to read and process as if it were inserted into the
|
directives</>, which specify another file to read and process as if
|
||||||
configuration file at this point. This feature allows a configuration
|
it were inserted into the configuration file at this point. This
|
||||||
file to be divided into physically separate parts.
|
feature allows a configuration file to be divided into physically
|
||||||
Include directives simply look like:
|
separate parts. Include directives simply look like:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
include 'filename'
|
include 'filename'
|
||||||
</programlisting>
|
</programlisting>
|
||||||
@ -337,7 +361,7 @@ include 'filename'
|
|||||||
<secondary>in configuration file</secondary>
|
<secondary>in configuration file</secondary>
|
||||||
</indexterm>
|
</indexterm>
|
||||||
There is also an <literal>include_if_exists</> directive, which acts
|
There is also an <literal>include_if_exists</> directive, which acts
|
||||||
the same as the <literal>include</> directive, except for the behavior
|
the same as the <literal>include</> directive, except
|
||||||
when the referenced file does not exist or cannot be read. A regular
|
when the referenced file does not exist or cannot be read. A regular
|
||||||
<literal>include</> will consider this an error condition, but
|
<literal>include</> will consider this an error condition, but
|
||||||
<literal>include_if_exists</> merely logs a message and continues
|
<literal>include_if_exists</> merely logs a message and continues
|
||||||
@ -350,43 +374,45 @@ include 'filename'
|
|||||||
<secondary>in configuration file</secondary>
|
<secondary>in configuration file</secondary>
|
||||||
</indexterm>
|
</indexterm>
|
||||||
The <filename>postgresql.conf</> file can also contain
|
The <filename>postgresql.conf</> file can also contain
|
||||||
<literal>include_dir</literal> directives, which specify an entire directory
|
<literal>include_dir</literal> directives, which specify an entire
|
||||||
of configuration files to include. It is used similarly:
|
directory of configuration files to include. These look like
|
||||||
<programlisting>
|
<programlisting>
|
||||||
include_dir 'directory'
|
include_dir 'directory'
|
||||||
</programlisting>
|
</programlisting>
|
||||||
Non-absolute directory names follow the same rules as single file include
|
Non-absolute directory names are taken as relative to the directory
|
||||||
directives: they are relative to the directory containing the referencing
|
containing the referencing configuration file. Within the specified
|
||||||
configuration file. Within that directory, only non-directory files whose
|
directory, only non-directory files whose names end with the
|
||||||
names end with the suffix <literal>.conf</literal> will be included. File
|
suffix <literal>.conf</literal> will be included. File names that
|
||||||
names that start with the <literal>.</literal> character are also excluded,
|
start with the <literal>.</literal> character are also ignored, to
|
||||||
to prevent mistakes as they are hidden on some platforms. Multiple files
|
prevent mistakes since such files are hidden on some platforms. Multiple
|
||||||
within an include directory are processed in file name order. The file names
|
files within an include directory are processed in file name order
|
||||||
are ordered by C locale rules, i.e. numbers before letters, and uppercase
|
(according to C locale rules, i.e. numbers before letters, and
|
||||||
letters before lowercase ones.
|
uppercase letters before lowercase ones).
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Include files or directories can be used to logically separate portions
|
Include files or directories can be used to logically separate portions
|
||||||
of the database configuration, rather than having a single large
|
of the database configuration, rather than having a single large
|
||||||
<filename>postgresql.conf</> file. Consider a company that has two
|
<filename>postgresql.conf</> file. Consider a company that has two
|
||||||
database servers, each with a different amount of memory. There are likely
|
database servers, each with a different amount of memory. There are
|
||||||
elements of the configuration both will share, for things such as logging.
|
likely elements of the configuration both will share, for things such
|
||||||
But memory-related parameters on the server will vary between the two. And
|
as logging. But memory-related parameters on the server will vary
|
||||||
there might be server specific customizations, too. One way to manage this
|
between the two. And there might be server specific customizations,
|
||||||
situation is to break the custom configuration changes for your site into
|
too. One way to manage this situation is to break the custom
|
||||||
three files. You could add this to the end of your
|
configuration changes for your site into three files. You could add
|
||||||
<filename>postgresql.conf</> file to include them:
|
this to the end of your <filename>postgresql.conf</> file to include
|
||||||
|
them:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
include 'shared.conf'
|
include 'shared.conf'
|
||||||
include 'memory.conf'
|
include 'memory.conf'
|
||||||
include 'server.conf'
|
include 'server.conf'
|
||||||
</programlisting>
|
</programlisting>
|
||||||
All systems would have the same <filename>shared.conf</>. Each server
|
All systems would have the same <filename>shared.conf</>. Each
|
||||||
with a particular amount of memory could share the same
|
server with a particular amount of memory could share the
|
||||||
<filename>memory.conf</>; you might have one for all servers with 8GB of RAM,
|
same <filename>memory.conf</>; you might have one for all servers
|
||||||
another for those having 16GB. And finally <filename>server.conf</> could
|
with 8GB of RAM, another for those having 16GB. And
|
||||||
have truly server-specific configuration information in it.
|
finally <filename>server.conf</> could have truly server-specific
|
||||||
|
configuration information in it.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
@ -396,22 +422,24 @@ include 'server.conf'
|
|||||||
<programlisting>
|
<programlisting>
|
||||||
include_dir 'conf.d'
|
include_dir 'conf.d'
|
||||||
</programlisting>
|
</programlisting>
|
||||||
Then you could name the files in the <filename>conf.d</> directory like this:
|
Then you could name the files in the <filename>conf.d</> directory
|
||||||
|
like this:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
00shared.conf
|
00shared.conf
|
||||||
01memory.conf
|
01memory.conf
|
||||||
02server.conf
|
02server.conf
|
||||||
</programlisting>
|
</programlisting>
|
||||||
This shows a clear order in which these files will be loaded. This is
|
This naming convention establishes a clear order in which these
|
||||||
important because only the last setting encountered when the server is
|
files will be loaded. This is important because only the last
|
||||||
reading its configuration will be used. Something set in
|
setting encountered for a particular parameter while the server is
|
||||||
<filename>conf.d/02server.conf</> in this example would override a value
|
reading configuration files will be used. In this example,
|
||||||
set in <filename>conf.d/01memory.conf</>.
|
something set in <filename>conf.d/02server.conf</> would override a
|
||||||
|
value set in <filename>conf.d/01memory.conf</>.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
You might instead use this configuration directory approach while naming
|
You might instead use this approach to naming the files
|
||||||
these files more descriptively:
|
descriptively:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
00shared.conf
|
00shared.conf
|
||||||
01memory-8GB.conf
|
01memory-8GB.conf
|
||||||
@ -421,7 +449,7 @@ include_dir 'conf.d'
|
|||||||
variation. This can help eliminate ambiguity when several servers have
|
variation. This can help eliminate ambiguity when several servers have
|
||||||
their configurations all stored in one place, such as in a version
|
their configurations all stored in one place, such as in a version
|
||||||
control repository. (Storing database configuration files under version
|
control repository. (Storing database configuration files under version
|
||||||
control is another good practice to consider).
|
control is another good practice to consider.)
|
||||||
</para>
|
</para>
|
||||||
</sect2>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
|
@ -32,23 +32,30 @@ ALTER SYSTEM RESET ALL
|
|||||||
<title>Description</title>
|
<title>Description</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
<command>ALTER SYSTEM</command> writes the configuration parameter
|
<command>ALTER SYSTEM</command> is used for changing server configuration
|
||||||
values to the <filename>postgresql.auto.conf</filename> file.
|
parameters across the entire database cluster. It can be more convenient
|
||||||
Setting the parameter to <literal>DEFAULT</literal>, or using the
|
than the traditional method of manually editing
|
||||||
<command>RESET</command> variant, removes the configuration entry from
|
the <filename>postgresql.conf</filename> file.
|
||||||
|
<command>ALTER SYSTEM</command> writes the given parameter setting to
|
||||||
|
the <filename>postgresql.auto.conf</filename> file, which is read in
|
||||||
|
addition to <filename>postgresql.conf</filename>.
|
||||||
|
Setting a parameter to <literal>DEFAULT</literal>, or using the
|
||||||
|
<command>RESET</command> variant, removes that configuration entry from the
|
||||||
<filename>postgresql.auto.conf</filename> file. Use <literal>RESET
|
<filename>postgresql.auto.conf</filename> file. Use <literal>RESET
|
||||||
ALL</literal> to clear all configuration entries. The values will
|
ALL</literal> to remove all such configuration entries.
|
||||||
be effective after reload of server configuration (SIGHUP) or in next
|
|
||||||
server start based on the type of configuration parameter modified.
|
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This command is not allowed inside transaction block or function.
|
Values set with <command>ALTER SYSTEM</command> will be effective after
|
||||||
|
the next server configuration reload (<systemitem>SIGHUP</>
|
||||||
|
or <literal>pg_ctl reload</>), or after the next server restart in the
|
||||||
|
case of parameters that can only be changed at server start.
|
||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
See <xref linkend="config-setting"> for other ways to set the parameters and
|
Only superusers can use <command>ALTER SYSTEM</command>. Also, since
|
||||||
how they become effective.
|
this command acts directly on the file system and cannot be rolled back,
|
||||||
|
it is not allowed inside a transaction block or function.
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
@ -60,7 +67,7 @@ ALTER SYSTEM RESET ALL
|
|||||||
<term><replaceable class="parameter">configuration_parameter</replaceable></term>
|
<term><replaceable class="parameter">configuration_parameter</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
Name of a settable run-time parameter. Available parameters are
|
Name of a settable configuration parameter. Available parameters are
|
||||||
documented in <xref linkend="runtime-config">.
|
documented in <xref linkend="runtime-config">.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
@ -70,11 +77,11 @@ ALTER SYSTEM RESET ALL
|
|||||||
<term><replaceable class="parameter">value</replaceable></term>
|
<term><replaceable class="parameter">value</replaceable></term>
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>
|
<para>
|
||||||
New value of parameter. Values can be specified as string
|
New value of the parameter. Values can be specified as string
|
||||||
constants, identifiers, numbers, or comma-separated lists of
|
constants, identifiers, numbers, or comma-separated lists of
|
||||||
these, as appropriate for the particular parameter.
|
these, as appropriate for the particular parameter.
|
||||||
<literal>DEFAULT</literal> can be written to specify to remove the
|
<literal>DEFAULT</literal> can be written to specify removing the
|
||||||
parameter and its value from <filename>postgresql.auto.conf</filename>
|
parameter and its value from <filename>postgresql.auto.conf</filename>.
|
||||||
</para>
|
</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
@ -85,9 +92,13 @@ ALTER SYSTEM RESET ALL
|
|||||||
<title>Notes</title>
|
<title>Notes</title>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
This command can't be used to set <xref linkend="guc-data-directory">
|
This command can't be used to set <xref linkend="guc-data-directory">,
|
||||||
and any parameters (e.g., <link linkend="runtime-config-preset">preset options</>)
|
nor parameters that are not allowed in <filename>postgresql.conf</>
|
||||||
that are not allowed in <filename>postgresql.conf</>.
|
(e.g., <link linkend="runtime-config-preset">preset options</>).
|
||||||
|
</para>
|
||||||
|
|
||||||
|
<para>
|
||||||
|
See <xref linkend="config-setting"> for other ways to set the parameters.
|
||||||
</para>
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
@ -102,10 +113,12 @@ ALTER SYSTEM SET wal_level = hot_standby;
|
|||||||
</para>
|
</para>
|
||||||
|
|
||||||
<para>
|
<para>
|
||||||
Set the <literal>authentication_timeout</>:
|
Undo that, restoring whatever setting was effective
|
||||||
|
in <filename>postgresql.conf</>:
|
||||||
<programlisting>
|
<programlisting>
|
||||||
ALTER SYSTEM SET authentication_timeout = 10;
|
ALTER SYSTEM RESET wal_level;
|
||||||
</programlisting></para>
|
</programlisting>
|
||||||
|
</para>
|
||||||
</refsect1>
|
</refsect1>
|
||||||
|
|
||||||
<refsect1>
|
<refsect1>
|
||||||
|
Loading…
Reference in New Issue
Block a user