granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/set.sgml

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/set.sgml,v 1.47 2000/08/07 00:51:18 tgl Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="SQL-SET">
   7  <refmeta>
   8   <refentrytitle id="SQL-SET-TITLE">SET</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11  <refnamediv>
  12   <refname>SET</refname>
  13   <refpurpose>Set run-time parameters</refpurpose>
  14  </refnamediv>
  15  <refsynopsisdiv>
  16   <synopsis>
  17 SET <replaceable class="PARAMETER">variable</replaceable> { TO | = } { <replaceable class="PARAMETER">value</replaceable> | '<replaceable class="PARAMETER">value</replaceable>' | DEFAULT }
  18 SET TIME ZONE { '<replaceable class="PARAMETER">timezone</replaceable>' | LOCAL | DEFAULT }
  19   </synopsis>
  20
  21   <refsect2 id="R2-SQL-SET-1">
  22    <title>Inputs</title>
  23    <para>
  24     <variablelist>
  25      <varlistentry>
  26       <term><replaceable class="PARAMETER">variable</replaceable></term>
  27       <listitem>
  28        <para>
  29         A settable run-time parameter.
  30        </para>
  31       </listitem>
  32      </varlistentry>
  33      <varlistentry>
  34       <term><replaceable class="PARAMETER">value</replaceable></term>
  35       <listitem>
  36        <para>
  37         New value of parameter.  <option>DEFAULT</option> can be
  38         used to specify resetting the parameter to its default
  39         value. Lists of strings are allowed, but more complex
  40         constructs may need to be single or double quoted.
  41        </para>
  42       </listitem>
  43      </varlistentry>
  44     </variablelist>
  45    </para>
  46   </refsect2>
  47
  48  </refsynopsisdiv>
  49
  50  <refsect1 id="R1-SQL-SET-1">
  51   <title>Description</title>
  52   <para>
  53    The <command>SET</command> command changes run-time configuration
  54    parameters. The following parameters can be altered:
  55
  56    <variablelist>
  57     <varlistentry>
  58      <term>CLIENT_ENCODING</term>
  59      <term>NAMES</term>
  60      <listitem>
  61       <para>
  62        Sets the multi-byte client encoding. The specified encoding
  63        must be supported by the backend.
  64       </para>
  65
  66       <para>
  67        This option is only available if
  68        <productname>Postgres</productname> is build with multibyte
  69        support.
  70       </para>
  71      </listitem>
  72     </varlistentry>
  73
  74     <varlistentry>
  75      <term>DATESTYLE</term>
  76      <listitem>
  77       <para>
  78        Choose the date/time representation style. Two separate
  79        settings are made: the default date/time output and the
  80        interpretation of ambiguous input.
  81       </para>
  82
  83       <para>
  84        The following are date/time output styles:
  85
  86        <variablelist>
  87         <varlistentry>
  88          <term>ISO</term>
  89          <listitem>
  90           <para>
  91            Use ISO 8601-style dates and times (<literal>YYYY-MM-DD
  92            HH:MM:SS</literal>). This is the default.
  93           </para>
  94          </listitem>
  95         </varlistentry>
  96
  97         <varlistentry>
  98          <term>SQL</term>
  99          <listitem>
 100           <para>
 101            Use Oracle/Ingres-style dates and times. Note that this
 102            style has nothing to do with SQL (which mandates ISO 8601
 103            style), the naming of this option is a historical accident.
 104           </para>
 105          </listitem>
 106         </varlistentry>
 107
 108         <varlistentry>
 109          <term>Postgres</term>
 110          <listitem>
 111           <para>
 112            Use traditional <productname>Postgres</productname> format.
 113           </para>
 114          </listitem>
 115         </varlistentry>
 116
 117         <varlistentry>
 118          <term>German</term>
 119          <listitem>
 120           <para>
 121            Use <literal>dd.mm.yyyy</literal> for numeric date representations.
 122           </para>
 123          </listitem>
 124         </varlistentry>
 125        </variablelist>
 126       </para>
 127
 128       <para>
 129        The following two options determine both a substyle of the
 130        <quote>SQL</quote> and <quote>Postgres</quote> output formats
 131        and the preferred interpretation of ambiguous date input.
 132
 133        <variablelist>
 134         <varlistentry>
 135          <term>European</term>
 136          <listitem>
 137           <para>
 138            Use <literal>dd/mm/yyyy</literal> for numeric date representations.
 139           </para>
 140          </listitem>
 141         </varlistentry>
 142
 143         <varlistentry>
 144          <term>NonEuropean</term>
 145          <term>US</term>
 146          <listitem>
 147           <para>
 148            Use <literal>mm/dd/yyyy</literal> for numeric date representations.
 149           </para>
 150          </listitem>
 151         </varlistentry>
 152        </variablelist>
 153       </para>
 154
 155       <para>
 156        A value for <command>SET DATESTYLE</command> can be one from
 157        the first list (output styles), or one from the second list
 158        (substyles), or one from each separated by a comma.
 159       </para>
 160
 161       <para>
 162        Date format initialization may be done by:
 163        <simplelist>
 164         <member>
 165          Setting the <envar>PGDATESTYLE</envar> environment variable.
 166          If PGDATESTYLE is set in the frontend environment of a client
 167          based on libpq, libpq will automatically set DATESTYLE to the
 168          value of PGDATESTYLE during connection startup.
 169         </member>
 170         <member>
 171          Running postmaster using the option <option>-o -e</option> to
 172          set dates to the <literal>European</literal> convention.
 173         </member>
 174        </simplelist>
 175       </para>
 176       <para>
 177        The <option>DateStyle</option> option is really only intended
 178        for porting applications. To format your date/time values to
 179        choice, use the <function>to_char</function> family of
 180        functions.
 181       </para>
 182      </listitem>
 183     </varlistentry>
 184
 185      <varlistentry>
 186       <term>SEED</term>
 187       <listitem>
 188        <para>
 189         Sets the internal seed for the random number generator.
 190
 191         <variablelist>
 192          <varlistentry>
 193           <term><replaceable class="parameter">value</replaceable></term>
 194           <listitem>
 195            <para>
 196             The value for the seed to be used by the
 197             <function>random</function> function. Allowed
 198             values are floating point numbers between 0 and 1, which
 199             are then multiplied by 2^31-1. This product will
 200             silently overflow if a number outside the range is used.
 201            </para>
 202
 203            <para>
 204             The seed can also be set by invoking the
 205             <function>setseed</function> SQL function:
 206
 207             <programlisting>
 208 SELECT setseed(<replaceable>value</replaceable>);
 209             </programlisting>
 210            </para>
 211           </listitem>
 212          </varlistentry>
 213         </variablelist>
 214        </para>
 215
 216       </listitem>
 217      </varlistentry>
 218
 219      <varlistentry>
 220       <term>SERVER_ENCODING</term>
 221       <listitem>
 222        <para>
 223         Sets the multi-byte server encoding.
 224        </para>
 225
 226        <para>
 227         This option is only available if
 228         <productname>Postgres</productname> was built with multibyte
 229         support.
 230        </para>
 231       </listitem>
 232      </varlistentry>
 233
 234      <varlistentry>
 235       <term>TIME ZONE</term>
 236       <term>TIMEZONE</term>
 237       <listitem>
 238        <para>
 239         The possible values for timezone depends on your operating
 240         system. For example, on Linux
 241         <filename>/usr/share/zoneinfo</filename> contains the database
 242         of time zones.
 243        </para>
 244        <para>
 245         Here are some valid values for timezone:
 246
 247         <variablelist>
 248          <varlistentry>
 249           <term>PST8PDT</term>
 250           <listitem>
 251            <para>
 252             Set the time zone for California.
 253            </para>
 254           </listitem>
 255          </varlistentry>
 256          <varlistentry>
 257           <term>Portugal</term>
 258           <listitem>
 259            <para>
 260             Set time zone for Portugal.
 261            </para>
 262           </listitem>
 263          </varlistentry>
 264          <varlistentry>
 265           <term>'Europe/Rome'</term>
 266           <listitem>
 267            <para>
 268             Set time zone for Italy.
 269            </para>
 270           </listitem>
 271          </varlistentry>
 272          <varlistentry>
 273           <term>LOCAL</term>
 274           <term>DEFAULT</term>
 275           <listitem>
 276            <para>
 277             Set the time zone to your local time zone (the one that
 278             your operating system defaults to).
 279            </para>
 280           </listitem>
 281          </varlistentry>
 282         </variablelist>
 283        </para>
 284        <para>
 285         If an invalid time zone is specified, the time zone
 286         becomes GMT (on most systems anyway).
 287        </para>
 288        <para>
 289         If the PGTZ environment variable is set in the frontend
 290         environment of a client based on libpq, libpq will automatically
 291         set TIMEZONE to the value of PGTZ during connection startup.
 292        </para>
 293       </listitem>
 294      </varlistentry>
 295
 296     </variablelist>
 297    </para>
 298
 299   <para>
 300    An extended list of other run-time parameters can be found in the
 301    <citetitle>Administrator's Guide</citetitle>.
 302   </para>
 303
 304   <para>
 305    Use <xref linkend="SQL-SHOW" endterm="SQL-SHOW-title"> to show the
 306    current setting of a parameters.
 307   </para>
 308
 309  </refsect1>
 310
 311  <refsect1>
 312   <title>Diagnostics</title>
 313   <para>
 314
 315    <variablelist>
 316     <varlistentry>
 317      <term><computeroutput>SET VARIABLE</computeroutput></term>
 318      <listitem>
 319       <para>
 320        Message returned if successful.
 321       </para>
 322      </listitem>
 323     </varlistentry>
 324
 325     <varlistentry>
 326      <term><computeroutput>ERROR:  not a valid option name: <replaceable>name</replaceable></computeroutput></term>
 327      <listitem>
 328       <para>
 329        The parameter you tried to set does not exist.
 330       </para>
 331      </listitem>
 332     </varlistentry>
 333
 334     <varlistentry>
 335      <term><computeroutput>ERROR:  permission denied</computeroutput></term>
 336      <listitem>
 337       <para>
 338        You must be a superuser to have access to certain settings.
 339       </para>
 340      </listitem>
 341     </varlistentry>
 342
 343     <varlistentry>
 344      <term><computeroutput>ERROR:  <replaceable>name</replaceable> can only be set at startup</computeroutput></term>
 345      <listitem>
 346       <para>
 347        Some parameters are fixed once the server is started.
 348       </para>
 349      </listitem>
 350     </varlistentry>
 351
 352    </variablelist>
 353   </para>
 354  </refsect1>
 355
 356
 357  <refsect1>
 358   <title>Examples</title>
 359   <para>
 360    Set the style of date to traditional Postgres with European conventions:
 361 <screen>
 362 SET DATESTYLE TO Postgres,European;
 363 </screen>
 364
 365    Set the timezone for Berkeley, California, using double quotes to
 366    preserve the uppercase attributes of the time zone specifier (note
 367    that the date/time format is ISO here):
 368
 369 <screen>
 370 SET TIME ZONE "PST8PDT";
 371 SELECT CURRENT_TIMESTAMP AS today;
 372
 373          today
 374 ------------------------
 375  1998-03-31 07:41:21-08
 376 </screen>
 377
 378    Set the timezone for Italy (note the required single or double quotes to handle
 379    the special characters):
 380
 381 <screen>
 382 SET TIME ZONE 'Europe/Rome';
 383 SELECT CURRENT_TIMESTAMP AS today;
 384
 385          today
 386 ------------------------
 387  1998-03-31 17:41:31+02
 388 </screen>
 389   </para>
 390  </refsect1>
 391
 392  <refsect1 id="R1-SQL-SET-3">
 393   <title>Compatibility</title>
 394
 395   <refsect2 id="R2-SQL-SET-4">
 396    <title>
 397     SQL92
 398    </title>
 399
 400    <para>
 401     The second syntax shown above (<literal>SET TIME ZONE</literal>)
 402     attempts to mimic <acronym>SQL92</acronym>. However, SQL allows
 403     only numeric time zone offsets. All other parameter settings as
 404     well as the first syntax shown above are a
 405     <productname>Postgres</productname> extension.
 406    </para>
 407   </refsect2>
 408  </refsect1>
 409 </refentry>
 410
 411 <!-- Keep this comment at the end of the file
 412 Local variables:
 413 mode:sgml
 414 sgml-omittag:nil
 415 sgml-shorttag:t
 416 sgml-minimize-attributes:nil
 417 sgml-always-quote-attributes:t
 418 sgml-indent-step:1
 419 sgml-indent-data:t
 420 sgml-parent-document:nil
 421 sgml-default-dtd-file:"../reference.ced"
 422 sgml-exposed-tags:nil
 423 sgml-local-catalogs:("/usr/lib/sgml/catalog")
 424 sgml-local-ecat-files:nil
 425 End:
 426 -->