pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedConfusing section of 'Setting Parameters'
3+ messages / 2 participants
[nested] [flat]
* Confusing section of 'Setting Parameters'
@ 2012-05-08 00:29 Josh Kupershmidt <schmiddy@gmail.com>
0 siblings, 1 reply; 3+ messages in thread
From: Josh Kupershmidt @ 2012-05-08 00:29 UTC (permalink / raw)
To: pgsql-docs
Hi all,
This bit of "Section 18.1. Setting Parameters"[1] is highly confusing:
[Some discussion about the 'include' directive, then jump immediately
to this next paragraph with no explanatory section header.]
| Use the same approach as the include directive, continuing normally if
| the file does not exist. A regular include will stop with an error
if the referenced
| file is missing, while include_if_exists does not. A warning about
the missing
| file will be logged.
IMO the paragraph above needs to clarify that it's talking about the
"include_if_exists" directive. "include_if_exists" is not even
mentioned in the first sentence of the paragraph, and I had to look at
the SGML for that section to be sure that the paragraph was indeed
describing "include_if_exists".
Attached are two possible fixes. First is a small patch
(include_if_exists.diff) to clarify the first sentence of that
paragraph.
Second, I think Section 18.1 as a whole could be much improved by
breaking it up into sub-sections; it seems too long and disjointed
as-is. I gave this reorganization a shot with a larger patch
(setting_parameters_subsections.diff) which includes the
include_if_exists clarification, and also breaks the page up into
three sub-sections. This is my preferred fix (for now -- I'll try to
send in some further explanation/consolidation of GUC contexts
relevant to that page later).
Josh
[1] http://www.postgresql.org/docs/devel/static/config-setting.html
Attachments: download all (2 files, .tar.gz)
include_if_exists.diff (text/x-patch, 1.1K) download
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
new file mode 100644
index e58dc18..881f0c4
*** a/doc/src/sgml/config.sgml
--- b/doc/src/sgml/config.sgml
*************** include 'filename'
*** 94,100 ****
<primary><literal>include_if_exists</></primary>
<secondary>in configuration file</secondary>
</indexterm>
! Use the same approach as the <literal>include</> directive, continuing
normally if the file does not exist. A regular <literal>include</>
will stop with an error if the referenced file is missing, while
<literal>include_if_exists</> does not. A warning about the missing
--- 94,101 ----
<primary><literal>include_if_exists</></primary>
<secondary>in configuration file</secondary>
</indexterm>
! The <literal>include_if_exists</> directive uses the same approach
! as the <literal>include</> directive, continuing
normally if the file does not exist. A regular <literal>include</>
will stop with an error if the referenced file is missing, while
<literal>include_if_exists</> does not. A warning about the missing
setting_parameters_subsections.diff (text/x-patch, 16.7K) download
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
new file mode 100644
index e58dc18..50f6806
*** a/doc/src/sgml/config.sgml
--- b/doc/src/sgml/config.sgml
***************
*** 18,62 ****
<sect1 id="config-setting">
<title>Setting Parameters</title>
! <para>
! All parameter names are case-insensitive. Every parameter takes a
! value of one of five types: Boolean, integer, floating point,
! string or enum. Boolean values can be written as <literal>on</literal>,
! <literal>off</literal>, <literal>true</literal>,
! <literal>false</literal>, <literal>yes</literal>,
! <literal>no</literal>, <literal>1</literal>, <literal>0</literal>
! (all case-insensitive) or any unambiguous prefix of these.
! </para>
! <para>
! Some settings specify a memory or time value. Each of these has an
! implicit unit, which is either kilobytes, blocks (typically eight
! kilobytes), milliseconds, seconds, or minutes. Default units can be
! found by referencing <structname>pg_settings</>.<structfield>unit</>.
! For convenience,
! a different unit can also be specified explicitly. Valid memory units
! are <literal>kB</literal> (kilobytes), <literal>MB</literal>
! (megabytes), and <literal>GB</literal> (gigabytes); valid time units
! are <literal>ms</literal> (milliseconds), <literal>s</literal>
! (seconds), <literal>min</literal> (minutes), <literal>h</literal>
! (hours), and <literal>d</literal> (days). Note that the multiplier
! for memory units is 1024, not 1000.
! </para>
! <para>
! Parameters of type <quote>enum</> are specified in the same way as string
! parameters, but are restricted to a limited set of values. The allowed
! values can be found
! from <structname>pg_settings</>.<structfield>enumvals</>.
! Enum parameter values are case-insensitive.
! </para>
! <para>
! One way to set these parameters is to edit the file
! <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
! which is normally kept in the data directory. (A default copy is
! installed there when the database cluster directory is
! initialized.) An example of what this file might look like is:
<programlisting>
# This is a comment
log_connections = yes
--- 18,65 ----
<sect1 id="config-setting">
<title>Setting Parameters</title>
! <sect2 id="config-setting-param-names-values">
! <title>Parameter Names and Values</title>
! <para>
! All parameter names are case-insensitive. Every parameter takes a
! value of one of five types: Boolean, integer, floating point,
! string or enum. Boolean values can be written as <literal>on</literal>,
! <literal>off</literal>, <literal>true</literal>,
! <literal>false</literal>, <literal>yes</literal>,
! <literal>no</literal>, <literal>1</literal>, <literal>0</literal>
! (all case-insensitive) or any unambiguous prefix of these.
! </para>
! <para>
! Some settings specify a memory or time value. Each of these has an
! implicit unit, which is either kilobytes, blocks (typically eight
! kilobytes), milliseconds, seconds, or minutes. Default units can be
! found by referencing <structname>pg_settings</>.<structfield>unit</>.
! For convenience,
! a different unit can also be specified explicitly. Valid memory units
! are <literal>kB</literal> (kilobytes), <literal>MB</literal>
! (megabytes), and <literal>GB</literal> (gigabytes); valid time units
! are <literal>ms</literal> (milliseconds), <literal>s</literal>
! (seconds), <literal>min</literal> (minutes), <literal>h</literal>
! (hours), and <literal>d</literal> (days). Note that the multiplier
! for memory units is 1024, not 1000.
! </para>
! <para>
! Parameters of type <quote>enum</> are specified in the same way as string
! parameters, but are restricted to a limited set of values. The allowed
! values can be found
! from <structname>pg_settings</>.<structfield>enumvals</>.
! Enum parameter values are case-insensitive.
! </para>
!
! <para>
! One way to set these parameters is to edit the file
! <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
! which is normally kept in the data directory. (A default copy is
! installed there when the database cluster directory is
! initialized.) An example of what this file might look like is:
<programlisting>
# This is a comment
log_connections = yes
*************** log_destination = 'syslog'
*** 64,195 ****
search_path = '"$user", public'
shared_buffers = 128MB
</programlisting>
! One parameter is specified per line. The equal sign between name and
! value is optional. Whitespace is insignificant and blank lines are
! ignored. Hash marks (<literal>#</literal>) designate the rest of the
! line as a comment. Parameter values that are not simple identifiers or
! numbers must be single-quoted. To embed a single quote in a parameter
! value, write either two quotes (preferred) or backslash-quote.
! </para>
! <para>
! <indexterm>
! <primary><literal>include</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! In addition to parameter settings, the <filename>postgresql.conf</>
! file can contain <firstterm>include directives</>, which specify
! another file to read and process as if it were inserted into the
! configuration file at this point. Include directives simply look like:
<programlisting>
include 'filename'
</programlisting>
! If the file name is not an absolute path, it is taken as relative to
! the directory containing the referencing configuration file.
! Inclusions can be nested.
! </para>
! <para>
! <indexterm>
! <primary><literal>include_if_exists</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! Use the same approach as the <literal>include</> directive, continuing
! normally if the file does not exist. A regular <literal>include</>
! will stop with an error if the referenced file is missing, while
! <literal>include_if_exists</> does not. A warning about the missing
! file will be logged.
! </para>
! <para>
! <indexterm>
! <primary>SIGHUP</primary>
! </indexterm>
! The configuration file is reread whenever the main server process receives a
! <systemitem>SIGHUP</> signal (which is most easily sent by means
! of <literal>pg_ctl reload</>). The main server process
! also propagates this signal to all currently running server
! processes so that existing sessions also get the new
! value. Alternatively, you can 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 configuration file will be ignored
! until the server is restarted. Invalid parameter settings in the
! configuration file are likewise ignored (but logged) during
! <systemitem>SIGHUP</> processing.
! </para>
! <para>
! A second way to set these configuration parameters is to give them
! as a command-line option to the <command>postgres</command> command, such as:
<programlisting>
postgres -c log_connections=yes -c log_destination='syslog'
</programlisting>
! Command-line options override any conflicting settings in
! <filename>postgresql.conf</filename>. Note that this means you won't
! be able to change the value on-the-fly by editing
! <filename>postgresql.conf</filename>, so while the command-line
! method might be convenient, it can cost you flexibility later.
! </para>
! <para>
! Occasionally it is useful to give a command line option to
! one particular session only. The environment variable
! <envar>PGOPTIONS</envar> can be used for this purpose on the
! client side:
<programlisting>
env PGOPTIONS='-c geqo=off' psql
</programlisting>
! (This works for any <application>libpq</>-based client application, not
! just <application>psql</application>.) Note that this won't work for
! parameters that are fixed when the server is started or that must be
! specified in <filename>postgresql.conf</filename>.
! </para>
! <para>
! Furthermore, it is possible to assign a set of parameter settings to
! a user or a database. Whenever a session is started, the default
! settings for the user and database involved are loaded. The
! commands <xref linkend="sql-alterrole">
! and <xref linkend="sql-alterdatabase">,
! respectively, are used to configure these settings. Per-database
! settings override anything received from the
! <command>postgres</command> command-line or the configuration
! file, and in turn are overridden by per-user settings; both are
! overridden by per-session settings.
! </para>
! <para>
! Some parameters can be changed in individual <acronym>SQL</acronym>
! sessions with the <xref linkend="SQL-SET">
! command, for example:
<screen>
SET ENABLE_SEQSCAN TO OFF;
</screen>
! If <command>SET</> is allowed, it overrides all other sources of
! values for the parameter. Some parameters cannot be changed via
! <command>SET</command>: for example, if they control behavior that
! cannot be changed without restarting the entire
! <productname>PostgreSQL</productname> server. Also,
! some <command>SET</command> or <command>ALTER</> parameter modifications
! require superuser permission.
! </para>
! <para>
! The <xref linkend="SQL-SHOW">
! command allows inspection of the current values of all parameters.
! </para>
! <para>
! The virtual table <structname>pg_settings</structname> also allows
! displaying and updating session run-time parameters; see <xref
! linkend="view-pg-settings"> for details and a description of the
! different variable types and when they can be changed.
! <structname>pg_settings</structname> is equivalent to <command>SHOW</>
! and <command>SET</>, but can be more convenient
! to use because it can be joined with other tables, or selected from using
! any desired selection condition. It also contains more information about
! what values are allowed for the parameters.
! </para>
</sect1>
<sect1 id="runtime-config-file-locations">
--- 67,210 ----
search_path = '"$user", public'
shared_buffers = 128MB
</programlisting>
! One parameter is specified per line. The equal sign between name and
! value is optional. Whitespace is insignificant and blank lines are
! ignored. Hash marks (<literal>#</literal>) designate the rest of the
! line as a comment. Parameter values that are not simple identifiers or
! numbers must be single-quoted. To embed a single quote in a parameter
! value, write either two quotes (preferred) or backslash-quote.
! </para>
! </sect2>
! <sect2 id="config-setting-include-directives">
! <title>Include Directives</title>
! <para>
! <indexterm>
! <primary><literal>include</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! In addition to parameter settings, the <filename>postgresql.conf</>
! file can contain <firstterm>include directives</>, which specify
! another file to read and process as if it were inserted into the
! configuration file at this point. Include directives simply look like:
<programlisting>
include 'filename'
</programlisting>
! If the file name is not an absolute path, it is taken as relative to
! the directory containing the referencing configuration file.
! Inclusions can be nested.
! </para>
! <para>
! <indexterm>
! <primary><literal>include_if_exists</></primary>
! <secondary>in configuration file</secondary>
! </indexterm>
! The <literal>include_if_exists</> directive uses the same approach
! as the <literal>include</> directive, continuing
! normally if the file does not exist. A regular <literal>include</>
! will stop with an error if the referenced file is missing, while
! <literal>include_if_exists</> does not. A warning about the missing
! file will be logged.
! </para>
! </sect2>
! <sect2 id="config-setting-ways-to-set">
! <title>Ways to Set Parameters</title>
! <para>
! <indexterm>
! <primary>SIGHUP</primary>
! </indexterm>
! The configuration file is reread whenever the main server process
! receives a
! <systemitem>SIGHUP</> signal (which is most easily sent by means
! of <literal>pg_ctl reload</>). The main server process
! also propagates this signal to all currently running server
! processes so that existing sessions also get the new
! value. Alternatively, you can 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 configuration file will be ignored
! until the server is restarted. Invalid parameter settings in the
! configuration file are likewise ignored (but logged) during
! <systemitem>SIGHUP</> processing.
! </para>
!
! <para>
! A second way to set these configuration parameters is to give them
! as a command-line option to the <command>postgres</command> command,
! such as:
<programlisting>
postgres -c log_connections=yes -c log_destination='syslog'
</programlisting>
! Command-line options override any conflicting settings in
! <filename>postgresql.conf</filename>. Note that this means you won't
! be able to change the value on-the-fly by editing
! <filename>postgresql.conf</filename>, so while the command-line
! method might be convenient, it can cost you flexibility later.
! </para>
! <para>
! Occasionally it is useful to give a command line option to
! one particular session only. The environment variable
! <envar>PGOPTIONS</envar> can be used for this purpose on the
! client side:
<programlisting>
env PGOPTIONS='-c geqo=off' psql
</programlisting>
! (This works for any <application>libpq</>-based client application, not
! just <application>psql</application>.) Note that this won't work for
! parameters that are fixed when the server is started or that must be
! specified in <filename>postgresql.conf</filename>.
! </para>
! <para>
! Furthermore, it is possible to assign a set of parameter settings to
! a user or a database. Whenever a session is started, the default
! settings for the user and database involved are loaded. The
! commands <xref linkend="sql-alterrole">
! and <xref linkend="sql-alterdatabase">,
! respectively, are used to configure these settings. Per-database
! settings override anything received from the
! <command>postgres</command> command-line or the configuration
! file, and in turn are overridden by per-user settings; both are
! overridden by per-session settings.
! </para>
! <para>
! Some parameters can be changed in individual <acronym>SQL</acronym>
! sessions with the <xref linkend="SQL-SET">
! command, for example:
<screen>
SET ENABLE_SEQSCAN TO OFF;
</screen>
! If <command>SET</> is allowed, it overrides all other sources of
! values for the parameter. Some parameters cannot be changed via
! <command>SET</command>: for example, if they control behavior that
! cannot be changed without restarting the entire
! <productname>PostgreSQL</productname> server. Also,
! some <command>SET</command> or <command>ALTER</> parameter modifications
! require superuser permission.
! </para>
! <para>
! The <xref linkend="SQL-SHOW">
! command allows inspection of the current values of all parameters.
! </para>
! <para>
! The virtual table <structname>pg_settings</structname> also allows
! displaying and updating session run-time parameters; see <xref
! linkend="view-pg-settings"> for details and a description of the
! different variable types and when they can be changed.
! <structname>pg_settings</structname> is equivalent to <command>SHOW</>
! and <command>SET</>, but can be more convenient
! to use because it can be joined with other tables, or selected from using
! any desired selection condition. It also contains more information about
! what values are allowed for the parameters.
! </para>
!
! </sect2>
</sect1>
<sect1 id="runtime-config-file-locations">
* Re: Confusing section of 'Setting Parameters'
@ 2012-05-11 03:05 Tom Lane <tgl@sss.pgh.pa.us>
parent: Josh Kupershmidt <schmiddy@gmail.com>
0 siblings, 1 reply; 3+ messages in thread
From: Tom Lane @ 2012-05-11 03:05 UTC (permalink / raw)
To: Josh Kupershmidt <schmiddy@gmail.com>; +Cc: pgsql-docs
Josh Kupershmidt <schmiddy@gmail.com> writes:
> This bit of "Section 18.1. Setting Parameters"[1] is highly confusing:
Yeah, that's badly in need of editing.
> Second, I think Section 18.1 as a whole could be much improved by
> breaking it up into sub-sections; it seems too long and disjointed
> as-is. I gave this reorganization a shot with a larger patch
> (setting_parameters_subsections.diff) which includes the
> include_if_exists clarification, and also breaks the page up into
> three sub-sections.
I think this is a good idea, but I didn't like your section division
at all. I broke it up like this instead:
Parameter Names and Values
Setting Parameters via the Configuration File
Other Ways to Set Parameters
Examining Parameter Settings
See what you think.
> This is my preferred fix (for now -- I'll try to
> send in some further explanation/consolidation of GUC contexts
> relevant to that page later).
Yeah, the discussion on the pg_settings page maybe should be moved here.
On the other hand, this is very introductory material, so it might not
be the best place for anything too detailed.
regards, tom lane
^ permalink raw reply [nested|flat] 3+ messages in thread
* Re: Confusing section of 'Setting Parameters'
@ 2012-05-11 04:38 Josh Kupershmidt <schmiddy@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 3+ messages in thread
From: Josh Kupershmidt @ 2012-05-11 04:38 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: pgsql-docs
On Thu, May 10, 2012 at 8:05 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
> I think this is a good idea, but I didn't like your section division
> at all. I broke it up like this instead:
>
> Parameter Names and Values
> Setting Parameters via the Configuration File
> Other Ways to Set Parameters
> Examining Parameter Settings
>
> See what you think.
Looks much better now, thanks.
Josh
^ permalink raw reply [nested|flat] 3+ messages in thread
end of thread, other threads:[~2012-05-11 04:38 UTC | newest]
Thread overview: 3+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2012-05-08 00:29 Confusing section of 'Setting Parameters' Josh Kupershmidt <schmiddy@gmail.com>
2012-05-11 03:05 ` Tom Lane <tgl@sss.pgh.pa.us>
2012-05-11 04:38 ` Josh Kupershmidt <schmiddy@gmail.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox