From 65d6e4cb5c62371dae6c236a7e709d503ae6ddf8 Mon Sep 17 00:00:00 2001
From: Tatsuo Ishii <ishii@postgresql.org>
Date: Wed, 18 Dec 2013 23:42:44 +0900
Subject: Add ALTER SYSTEM command to edit the server configuration file.

Patch contributed by Amit Kapila. Reviewed by Hari Babu, Masao Fujii,
Boszormenyi Zoltan, Andres Freund, Greg Smith and others.
---
 doc/src/sgml/config.sgml           |  13 +++++
 doc/src/sgml/ref/allfiles.sgml     |   1 +
 doc/src/sgml/ref/alter_system.sgml | 114 +++++++++++++++++++++++++++++++++++++
 doc/src/sgml/reference.sgml        |   1 +
 doc/src/sgml/storage.sgml          |   6 ++
 5 files changed, 135 insertions(+)
 create mode 100644 doc/src/sgml/ref/alter_system.sgml

(limited to 'doc/src')

diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index f0794467ba4..5575df51602 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -158,6 +158,19 @@ SET ENABLE_SEQSCAN TO OFF;
      require superuser permission to change via <command>SET</command> or
      <command>ALTER</>.
     </para>
+
+    <para>
+     Another way to change configuration parameters persistently is by
+     use of <xref linkend="SQL-ALTERSYSTEM">
+     command, for example:
+<screen>
+ALTER SYSTEM SET checkpoint_timeout TO 600;
+</screen>
+     This command will allow users to change values persistently
+     through SQL command. The values will be effective after reload of server configuration
+     (<acronym>SIGHUP</>) or server startup. The effect of this command is similar to when
+     user manually changes values in <filename>postgresql.conf</filename>.
+    </para>
    </sect2>
 
    <sect2 id="config-setting-examining">
diff --git a/doc/src/sgml/ref/allfiles.sgml b/doc/src/sgml/ref/allfiles.sgml
index 5846974feb9..ce7a5e3cb6c 100644
--- a/doc/src/sgml/ref/allfiles.sgml
+++ b/doc/src/sgml/ref/allfiles.sgml
@@ -30,6 +30,7 @@ Complete list of usable sgml source files in this directory.
 <!ENTITY alterSchema        SYSTEM "alter_schema.sgml">
 <!ENTITY alterServer        SYSTEM "alter_server.sgml">
 <!ENTITY alterSequence      SYSTEM "alter_sequence.sgml">
+<!ENTITY alterSystem        SYSTEM "alter_system.sgml">
 <!ENTITY alterTable         SYSTEM "alter_table.sgml">
 <!ENTITY alterTableSpace    SYSTEM "alter_tablespace.sgml">
 <!ENTITY alterTSConfig      SYSTEM "alter_tsconfig.sgml">
diff --git a/doc/src/sgml/ref/alter_system.sgml b/doc/src/sgml/ref/alter_system.sgml
new file mode 100644
index 00000000000..3ccc6afd516
--- /dev/null
+++ b/doc/src/sgml/ref/alter_system.sgml
@@ -0,0 +1,114 @@
+<!--
+doc/src/sgml/ref/alter_system.sgml
+PostgreSQL documentation
+-->
+
+<refentry id="SQL-ALTERSYSTEM">
+ <refmeta>
+  <refentrytitle>ALTER SYSTEM</refentrytitle>
+  <manvolnum>7</manvolnum>
+  <refmiscinfo>SQL - Language Statements</refmiscinfo>
+ </refmeta>
+
+ <refnamediv>
+  <refname>ALTER SYSTEM</refname>
+  <refpurpose>change a server configuration parameter</refpurpose>
+ </refnamediv>
+
+ <indexterm zone="sql-altersystem">
+  <primary>ALTER SYSTEM</primary>
+ </indexterm>
+
+ <refsynopsisdiv>
+<synopsis>
+ALTER SYSTEM SET <replaceable class="PARAMETER">configuration_parameter</replaceable> { TO | = } { <replaceable class="PARAMETER">value</replaceable> | '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT }
+</synopsis>
+ </refsynopsisdiv>
+
+ <refsect1>
+  <title>Description</title>
+
+  <para>
+   <command>ALTER SYSTEM</command> writes the configuration parameter
+   values to the <filename>postgresql.auto.conf</filename> file. With
+   <literal>DEFAULT</literal>, it removes a configuration entry from
+   <filename>postgresql.auto.conf</filename> file. The values will be
+   effective after reload of server configuration (SIGHUP) or in next 
+   server start based on the type of configuration parameter modified.
+  </para>
+
+  <para>
+   This command is not allowed inside transaction block or function.
+  </para>
+  
+  <para>
+   See <xref linkend="config-setting"> for other ways to set the parameters and 
+   how they become effective.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>Parameters</title>
+
+  <variablelist>
+   <varlistentry>
+    <term><replaceable class="parameter">configuration_parameter</replaceable></term>
+    <listitem>
+     <para>
+      Name of a settable run-time parameter.  Available parameters are
+      documented in <xref linkend="runtime-config">.
+     </para>
+    </listitem>
+   </varlistentry>
+
+   <varlistentry>
+    <term><replaceable class="parameter">value</replaceable></term>
+    <listitem>
+     <para>
+      New value of parameter.  Values can be specified as string
+      constants, identifiers, numbers, or comma-separated lists of
+      these, as appropriate for the particular parameter.
+      <literal>DEFAULT</literal> can be written to specify to remove the
+      parameter and its value from <filename>postgresql.auto.conf</filename>
+     </para>
+    </listitem>
+   </varlistentry>
+  </variablelist>
+ </refsect1>
+
+ <refsect1>
+  <title>Examples</title>
+
+  <para>
+   Set the <literal>wal_level</>:
+<programlisting>
+ALTER SYSTEM SET wal_level = hot_standby;
+</programlisting>
+  </para>
+
+  <para>
+   Set the <literal>authentication_timeout</>:
+<programlisting>
+ALTER SYSTEM SET authentication_timeout = 10;
+</programlisting></para>
+ </refsect1>
+
+ <refsect1>
+  <title>Compatibility</title>
+
+  <para>
+   The <command>ALTER SYSTEM</command> statement is a
+   <productname>PostgreSQL</productname> extension.
+  </para>
+ </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="SQL-SET"></member>
+   <member><xref linkend="SQL-SHOW"></member>
+  </simplelist>
+ </refsect1>
+
+</refentry>
diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml
index d967f666b91..87e8e9ee8ff 100644
--- a/doc/src/sgml/reference.sgml
+++ b/doc/src/sgml/reference.sgml
@@ -58,6 +58,7 @@
    &alterSchema;
    &alterSequence;
    &alterServer;
+   &alterSystem;
    &alterTable;
    &alterTableSpace;
    &alterTSConfig;
diff --git a/doc/src/sgml/storage.sgml b/doc/src/sgml/storage.sgml
index 09b3f1028c1..1f3f1f9bf97 100644
--- a/doc/src/sgml/storage.sgml
+++ b/doc/src/sgml/storage.sgml
@@ -125,6 +125,12 @@ Item
  <entry>Subdirectory containing WAL (Write Ahead Log) files</entry>
 </row>
 
+<row>
+ <entry><filename>postgresql.auto.conf</></entry>
+ <entry>A file used for storing configuration parameters that are set by
+<command>ALTER SYSTEM</command></entry>
+</row>
+
 <row>
  <entry><filename>postmaster.opts</></entry>
  <entry>A file recording the command-line options the server was
-- 
cgit v1.2.3