Thread: Re: Should enum GUCs be listed as such in config.sgml?

bruce wrote:
> Tom Lane wrote:
> > Currently, config.sgml still describes the new "enum" GUC variables
> > as being of type "string" --- but pg_settings says they are "enum".
> > This is not very consistent, but I wonder whether changing the docs
> > would be more confusing or less so.  I note that section 18.1 doesn't
> > mention the enum alternative either.
> 
> I looked into this and I think the documentation is fine.  If enums
> didn't require quotes but strings did, we would document them
> differently, but the fact is that enums are the same as strings except
> enums have a limited number of possible values --- that isn't something
> that is usually identified in a variable type definition heading.

Looking further, it seems we still have an inconsistency problem because
pg_settings mentions enum;  should we just change that to 'string'?

--  Bruce Momjian  <bruce@momjian.us>        http://momjian.us EnterpriseDB
http://enterprisedb.com
 + If your life is a hard drive, Christ can be your backup. +

Bruce Momjian <bruce@momjian.us> writes:
> bruce wrote:
>> Tom Lane wrote:
>>> Currently, config.sgml still describes the new "enum" GUC variables
>>> as being of type "string" --- but pg_settings says they are "enum".
>>> This is not very consistent, but I wonder whether changing the docs
>>> would be more confusing or less so.  I note that section 18.1 doesn't
>>> mention the enum alternative either.
>> 
>> I looked into this and I think the documentation is fine.  If enums
>> didn't require quotes but strings did, we would document them
>> differently, but the fact is that enums are the same as strings except
>> enums have a limited number of possible values --- that isn't something
>> that is usually identified in a variable type definition heading.

By that logic, we should not distinguish integers and floats.  One's
just a restricted form of the other.

> Looking further, it seems we still have an inconsistency problem because
> pg_settings mentions enum;  should we just change that to 'string'?

No, and in fact pg_settings is the counterexample to your conclusion
that it's okay to pretend enums are the same as strings: since it has an
enumvals column that's populated for enums and not for strings, there
is clearly a genuine user-visible difference.


Last I checked, Magnus had promised to come up with suitable
documentation changes for this patch, but then he went off sailing...
        regards, tom lane

Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
>> bruce wrote:
>>> Tom Lane wrote:
>>>> Currently, config.sgml still describes the new "enum" GUC variables
>>>> as being of type "string" --- but pg_settings says they are "enum".
>>>> This is not very consistent, but I wonder whether changing the docs
>>>> would be more confusing or less so.  I note that section 18.1 doesn't
>>>> mention the enum alternative either.
>>> I looked into this and I think the documentation is fine.  If enums
>>> didn't require quotes but strings did, we would document them
>>> differently, but the fact is that enums are the same as strings except
>>> enums have a limited number of possible values --- that isn't something
>>> that is usually identified in a variable type definition heading.
> 
> By that logic, we should not distinguish integers and floats.  One's
> just a restricted form of the other.
> 
>> Looking further, it seems we still have an inconsistency problem because
>> pg_settings mentions enum;  should we just change that to 'string'?
> 
> No, and in fact pg_settings is the counterexample to your conclusion
> that it's okay to pretend enums are the same as strings: since it has an
> enumvals column that's populated for enums and not for strings, there
> is clearly a genuine user-visible difference.
> 
> 
> Last I checked, Magnus had promised to come up with suitable
> documentation changes for this patch, but then he went off sailing...

Yes, it's on my TODO list waiting to bubble up to the top. Not forgotten
(yet).

//Magnus

Tom Lane wrote:
> Bruce Momjian <bruce@momjian.us> writes:
>> bruce wrote:
>>> Tom Lane wrote:
>>>> Currently, config.sgml still describes the new "enum" GUC variables
>>>> as being of type "string" --- but pg_settings says they are "enum".
>>>> This is not very consistent, but I wonder whether changing the docs
>>>> would be more confusing or less so.  I note that section 18.1 doesn't
>>>> mention the enum alternative either.
>>> I looked into this and I think the documentation is fine.  If enums
>>> didn't require quotes but strings did, we would document them
>>> differently, but the fact is that enums are the same as strings except
>>> enums have a limited number of possible values --- that isn't something
>>> that is usually identified in a variable type definition heading.
>
> By that logic, we should not distinguish integers and floats.  One's
> just a restricted form of the other.
>
>> Looking further, it seems we still have an inconsistency problem because
>> pg_settings mentions enum;  should we just change that to 'string'?
>
> No, and in fact pg_settings is the counterexample to your conclusion
> that it's okay to pretend enums are the same as strings: since it has an
> enumvals column that's populated for enums and not for strings, there
> is clearly a genuine user-visible difference.
>
>
> Last I checked, Magnus had promised to come up with suitable
> documentation changes for this patch, but then he went off sailing...

Meh, I seem to have forgotten this one again. Here's a suggestion, seems
ok, or were you thinking about something more?

//Magnus
diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml
index b0de16e..1cfa8bc 100644
--- a/doc/src/sgml/config.sgml
+++ b/doc/src/sgml/config.sgml
@@ -20,8 +20,8 @@

    <para>
     All parameter names are case-insensitive. Every parameter takes a
-    value of one of four types: Boolean, integer, floating point,
-    or string. Boolean values can be written as <literal>ON</literal>,
+    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>
@@ -43,6 +43,12 @@
    </para>

    <para>
+    Enum settings are specified the same way as string settings, but they
+    are limited in which strings are accepted. For each setting the available
+    are listed in <literal>pg_settings.enumvals</>.
+   </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. (<application>initdb</>
@@ -1329,7 +1335,7 @@ SET ENABLE_SEQSCAN TO OFF;
      </varlistentry>

      <varlistentry id="guc-wal-sync-method" xreflabel="wal_sync_method">
-      <term><varname>wal_sync_method</varname> (<type>string</type>)</term>
+      <term><varname>wal_sync_method</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>wal_sync_method</> configuration parameter</primary>
       </indexterm>
@@ -2464,7 +2470,7 @@ local0.*    /var/log/postgresql
      </varlistentry>

      <varlistentry id="guc-syslog-facility" xreflabel="syslog_facility">
-      <term><varname>syslog_facility</varname> (<type>string</type>)</term>
+      <term><varname>syslog_facility</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>syslog_facility</> configuration parameter</primary>
       </indexterm>
@@ -2511,7 +2517,7 @@ local0.*    /var/log/postgresql
      <variablelist>

      <varlistentry id="guc-client-min-messages" xreflabel="client_min_messages">
-      <term><varname>client_min_messages</varname> (<type>string</type>)</term>
+      <term><varname>client_min_messages</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>client_min_messages</> configuration parameter</primary>
       </indexterm>
@@ -2532,7 +2538,7 @@ local0.*    /var/log/postgresql
      </varlistentry>

      <varlistentry id="guc-log-min-messages" xreflabel="log_min_messages">
-      <term><varname>log_min_messages</varname> (<type>string</type>)</term>
+      <term><varname>log_min_messages</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_min_messages</> configuration parameter</primary>
       </indexterm>
@@ -2554,7 +2560,7 @@ local0.*    /var/log/postgresql
      </varlistentry>

      <varlistentry id="guc-log-error-verbosity" xreflabel="log_error_verbosity">
-      <term><varname>log_error_verbosity</varname> (<type>string</type>)</term>
+      <term><varname>log_error_verbosity</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_error_verbosity</> configuration parameter</primary>
       </indexterm>
@@ -2570,7 +2576,7 @@ local0.*    /var/log/postgresql
      </varlistentry>

      <varlistentry id="guc-log-min-error-statement" xreflabel="log_min_error_statement">
-      <term><varname>log_min_error_statement</varname> (<type>string</type>)</term>
+      <term><varname>log_min_error_statement</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_min_error_statement</> configuration parameter</primary>
       </indexterm>
@@ -3056,7 +3062,7 @@ local0.*    /var/log/postgresql
      </varlistentry>

      <varlistentry id="guc-log-statement" xreflabel="log_statement">
-      <term><varname>log_statement</varname> (<type>string</type>)</term>
+      <term><varname>log_statement</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>log_statement</> configuration parameter</primary>
       </indexterm>
@@ -3314,7 +3320,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>

      <varlistentry id="guc-track-functions" xreflabel="track_functions">
-      <term><varname>track_functions</varname> (<type>string</type>)</term>
+      <term><varname>track_functions</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>track_functions</> configuration parameter</primary>
       </indexterm>
@@ -3828,7 +3834,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
       <indexterm>
        <primary><varname>default_transaction_isolation</> configuration parameter</primary>
       </indexterm>
-      <term><varname>default_transaction_isolation</varname> (<type>string</type>)</term>
+      <term><varname>default_transaction_isolation</varname> (<type>enum</type>)</term>
       <listitem>
        <para>
         Each SQL transaction has an isolation level, which can be
@@ -3871,7 +3877,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>

      <varlistentry id="guc-session-replication-role" xreflabel="session_replication_role">
-      <term><varname>session_replication_role</varname> (<type>string</type>)</term>
+      <term><varname>session_replication_role</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>session_replication_role</> configuration parameter</primary>
       </indexterm>
@@ -3933,7 +3939,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>

      <varlistentry id="guc-xmlbinary" xreflabel="xmlbinary">
-      <term><varname>xmlbinary</varname> (<type>string</type>)</term>
+      <term><varname>xmlbinary</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>xmlbinary</> configuration parameter</primary>
       </indexterm>
@@ -3960,7 +3966,7 @@ COPY postgres_log FROM '/full/path/to/logfile.csv' WITH csv;
      </varlistentry>

      <varlistentry id="guc-xmloption" xreflabel="xmloption">
-      <term><varname>xmloption</varname> (<type>string</type>)</term>
+      <term><varname>xmloption</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>xmloption</> configuration parameter</primary>
       </indexterm>
@@ -4026,7 +4032,7 @@ SET XML OPTION { DOCUMENT | CONTENT };
      </varlistentry>

      <varlistentry id="guc-intervalstyle" xreflabel="IntervalStyle">
-      <term><varname>IntervalStyle</varname> (<type>string</type>)</term>
+      <term><varname>IntervalStyle</varname> (<type>enum</type>)</term>
       <indexterm>
        <primary><varname>IntervalStyle</> configuration parameter</primary>
       </indexterm>
@@ -4514,7 +4520,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
      </varlistentry>

      <varlistentry id="guc-backslash-quote" xreflabel="backslash_quote">
-      <term><varname>backslash_quote</varname> (<type>string</type>)</term>
+      <term><varname>backslash_quote</varname> (<type>enum</type>)</term>
       <indexterm><primary>strings</><secondary>backslash quotes</></>
       <indexterm>
        <primary><varname>backslash_quote</> configuration parameter</primary>
@@ -4602,7 +4608,7 @@ dynamic_library_path = 'C:\tools\postgresql;H:\my_project\lib;$libdir'
      </varlistentry>

      <varlistentry id="guc-regex-flavor" xreflabel="regex_flavor">
-      <term><varname>regex_flavor</varname> (<type>string</type>)</term>
+      <term><varname>regex_flavor</varname> (<type>enum</type>)</term>
       <indexterm><primary>regular expressions</></>
       <indexterm>
        <primary><varname>regex_flavor</> configuration parameter</primary>

Magnus Hagander <magnus@hagander.net> writes:
> Tom Lane wrote:
>> Last I checked, Magnus had promised to come up with suitable
>> documentation changes for this patch, but then he went off sailing...

> Meh, I seem to have forgotten this one again. Here's a suggestion, seems
> ok, or were you thinking about something more?

Needs a bit of proofreading but this is more or less what I had in
mind.

> +    Enum settings are specified the same way as string settings, but they
> +    are limited in which strings are accepted. For each setting the available
> +    are listed in <literal>pg_settings.enumvals</>.

IIRC the comparisons are case-insensitive; if so the fact should be
mentioned here.
        regards, tom lane

Tom Lane wrote:
> Magnus Hagander <magnus@hagander.net> writes:
>> Tom Lane wrote:
>>> Last I checked, Magnus had promised to come up with suitable
>>> documentation changes for this patch, but then he went off sailing...
> 
>> Meh, I seem to have forgotten this one again. Here's a suggestion, seems
>> ok, or were you thinking about something more?
> 
> Needs a bit of proofreading but this is more or less what I had in
> mind.
> 
>> +    Enum settings are specified the same way as string settings, but they
>> +    are limited in which strings are accepted. For each setting the available
>> +    are listed in <literal>pg_settings.enumvals</>.
> 
> IIRC the comparisons are case-insensitive; if so the fact should be
> mentioned here.

Updated, added, and applied.

//Magnus