path: root/doc/src/sgml/ref/set.sgml

<REFENTRY ID="SQL-SET">
 <REFMETA>
  <REFENTRYTITLE>
   SET
  </REFENTRYTITLE>
  <REFMISCINFO>SQL - Language Statements</REFMISCINFO>
 </REFMETA>
 <REFNAMEDIV>
  <REFNAME>
   SET
  </REFNAME>
  <REFPURPOSE>
   Set run-time parameters for session
  </REFPURPOSE>
 </refnamediv>
 <REFSYNOPSISDIV>
  <REFSYNOPSISDIVINFO>
   <DATE>1998-09-24</DATE>
  </REFSYNOPSISDIVINFO>
  <SYNOPSIS>
SET <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE> { TO | = } { '<REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>' | DEFAULT }
SET TIME ZONE { '<REPLACEABLE CLASS="PARAMETER">timezone</REPLACEABLE>' | LOCAL };
  </SYNOPSIS>

  <REFSECT2 ID="R2-SQL-SET-1">
   <REFSECT2INFO>
    <DATE>1998-09-24</DATE>
   </REFSECT2INFO>
   <TITLE>
    Inputs
   </TITLE>
   <PARA>
		
    <VARIABLELIST>
     <VARLISTENTRY>
      <TERM>
       <REPLACEABLE CLASS="PARAMETER">variable</REPLACEABLE>
      </TERM>
      <LISTITEM>
       <para>
	Settable global parameter.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term>
       <REPLACEABLE CLASS="PARAMETER">value</REPLACEABLE>
      </term>
      <listitem>
       <PARA>
	New value of parameter.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    The possible variables and allowed values are:
		
    <VARIABLELIST>
     <VARLISTENTRY>
      <TERM>
       DateStyle
      </TERM>
      <LISTITEM>
       <PARA>
	
	<VARIABLELIST>
	 <VARLISTENTRY>
	  <TERM>
	   ISO
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    use ISO 8601-style dates and times
	   </para>
	  </listitem>
	 </varlistentry>
	 <VARLISTENTRY>
	  <TERM>
	   SQL
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    use Oracle/Ingres-style dates and times
	   </para>
	  </listitem>
	 </varlistentry>
	 <VARLISTENTRY>
	  <TERM>
	   Postgres
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    use traditional <productname>Postgres</productname> format
	   </para>
	  </listitem>
	 </varlistentry>
	 <VARLISTENTRY>
	  <TERM>
	   European
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    use dd/mm/yyyy for numeric date representations.
	   </para>
	  </listitem>
	 </varlistentry>
	 <VARLISTENTRY>
	  <TERM>
	   NonEuropean
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    use mm/dd/yyyy for numeric date representations.
	   </para>
	  </listitem>
	 </varlistentry>
	 <VARLISTENTRY>
	  <TERM>
	   German
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    use dd.mm.yyyy for numeric date representations.
	   </para>
	  </listitem>
	 </varlistentry>
	 <VARLISTENTRY>
	  <TERM>
	   US
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    same as 'NonEuropean'
	   </para>
	  </listitem>
	 </varlistentry>
	 <VARLISTENTRY>
	  <TERM>
	   default
	  </TERM>
	  <LISTITEM>
	   <PARA>
	    restores the default values ('US,Postgres')
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    Date format initialization my be done by:
    <simplelist>
     <member>
      Setting PGDATESTYLE environment variable.
     </member>
     <member>
      Running postmaster using -oe parameter to set
      dates to the 'European' convention.
      Note that this affects only the some combinations of date styles; for example
      the ISO style is not affected by this parameter.
     </member>
     <member>
      Changing variables in 
      <filename>src/backend/utils/init/globals.c</filename>.
     </member>
    </simplelist>
   </para>
   <para>
    The variables in <filename>globals.c</filename> which can be changed are:
    <simplelist>
     <member>
      bool EuroDates = false | true
     </member>
     <member>
      int  DateStyle = USE_ISO_DATES | USE_POSTGRES_DATES | USE_SQL_DATES | USE_GERMAN_DATES
     </member>
    </simplelist>

   </para>
   <para>
    <variablelist>
     <varlistentry>
      <term>
       TIMEZONE
      </term>
      <listitem>
       <para>
	The possible values for timezone depends on your operating
	system. For example on Linux /usr/lib/zoneinfo contains the
	database of timezones.
       </para>
       <para>
	Here are some valid values for timezone:
				
	<variablelist>
	 <varlistentry>
	  <term>
	   'PST8PDT'
	  </term>
	  <listitem>
	   <para>
	    set the timezone for California
	   </para>
	  </listitem>
	 </varlistentry>
	 <varlistentry>
	  <term>
	   'Portugal'
	  </term>
	  <listitem>
	   <para>
	    set time zone for Portugal.
	   </para>
	  </listitem>
	 </varlistentry>
	 <varlistentry>
	  <term>
	   'Europe/Rome'
	  </term>
	  <listitem>
	   <para>
	    set time zone for Italy.
	   </para>
	  </listitem>
	 </varlistentry>
	 <varlistentry>
	  <term>
	   DEFAULT
	  </term>
	  <listitem>
	   <para>
	    set time zone to your local timezone
	    (value of the TZ environment variable).
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
       </para>
       <para>
	If an invalid time zone is specified, the time zone
	becomes GMT (on most systems anyway).
       </para>
       <para>
	A frontend which uses libpq may be initialized by setting the PGTZ
	environment variable.
       </para>
       <para>
	The second syntax shown above, allows one to set the timezone
	with a syntax similar to SQL92 <command>SET TIME ZONE</command>.
	The LOCAL keyword is just an alternate form
	of DEFAULT for SQL92 compatibility.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    There are also several internal or optimization
    parameters which can be specified
    by the <command>SET</command> command:
    
    <variablelist>
     <varlistentry>
      <term>
       COST_HEAP
      </term>
      <listitem>
       <para>
	Sets the default cost of a heap scan for use by the optimizer.
	
	<variablelist>
	 <varlistentry>
	  <term>
	   <replaceable class="parameter">float4</replaceable>
	  </term>
	  <listitem>
	   <para>
	    Set the cost of a heap scan to the specified floating point value.
	   </para>
	  </listitem>
	 </varlistentry>
	 
	 <varlistentry>
	  <term>
	   DEFAULT
	  </term>
	  <listitem>
	   <para>
	    Sets the cost of a heap scan to the default value.
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
       </para>
       <para>
	The frontend may be initialized by setting the PGCOSTHEAP
	environment variable.
       </para>
       <variablelist>
	<varlistentry>
	 <term>
	  COST_INDEX
	 </term>
	 <listitem>
	  <para>
	   Sets the default cost of an index scan for use by the optimizer.
	  </para>
	 </listitem>
	</varlistentry>
	
	<varlistentry>
	 <term>
	  <replaceable class="parameter">float4</replaceable>
	 </term>
	 <listitem>
	  <para>
	   Set the cost of an index scan to the specified floating point value.
	  </para>
	 </listitem>
	</varlistentry>
	
	<varlistentry>
	 <term>
	  DEFAULT
	 </term>
	 <listitem>
	  <para>
	   Sets the cost of an index scan to the default value.
	  </para>
	 </listitem>
	</varlistentry>
       </variablelist>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    The frontend may be initialized by setting the PGCOSTINDEX
    environment variable.
    
    <variablelist>
     <varlistentry>
      <term>
       GEQO
      </term>
      <listitem>
       <para>
	Sets the threshold for using the genetic optimizer algorithm.
       </para>
       
       <variablelist>
	<varlistentry>
	 <term>
	  On
	 </term>
	 <listitem>
	  <para>
	   enables the genetic optimizer algorithm
	   for statements with 6 or more tables.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  On=<replaceable class="parameter">#</replaceable>
	 </term>
	 <listitem>
	  <para>
	   Takes an integer argument to enable the genetic optimizer algorithm
	   for statements with <replaceable class="parameter">#</replaceable>
	   or more tables in the query.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  Off
	 </term>
	 <listitem>
	  <para>
	   disables the genetic optimizer algorithm.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  DEFAULT
	 </term>
	 <listitem>
	  <para>
	   Equivalent to specifying <command>SET GEQO='on'</command>
	  </para>
	 </listitem>
	</varlistentry>
       </variablelist>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    This algorithm is on by default, which used GEQO for
    statements of eleven or more tables.
    (See the chapter on GEQO in the Programmer's Guide
    for more information).
   </para>
   <para>
    The frontend may be initialized by setting PGGEQO
    environment variable.
   </para>
   <para>
    It may be useful when joining big relations with
    small ones. This algorithm is off by default.
    It's not used by GEQO anyway.
    
    <variablelist>
     <varlistentry>
      <term>
       KSQO
      </term>
      <listitem>
       <para>
	<firstterm>Key Set Query Optimizer</firstterm> forces the query optimizer
	to optimize repetative OR clauses such as generated by
	<productname>MicroSoft Access</productname>:
       </para>
       
       <variablelist>
	<varlistentry>
	 <term>
	  On
	 </term>
	 <listitem>
	  <para>
	   enables this optimization.
	  </para>
	 </listitem>
	</varlistentry>
	
	<varlistentry>
	 <term>
	  Off
	 </term>
	 <listitem>
	  <para>
	   disables this optimization.
	  </para>
	 </listitem>
	</varlistentry>
	
	<varlistentry>
	 <term>
	  DEFAULT
	 </term>
	 <listitem>
	  <para>
	   Equivalent to specifying <command>SET KSQO='off'</command>.
	  </para>
	 </listitem>
	</varlistentry>
       </variablelist>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
   <para>
    It may be useful when joining big relations with
    small ones. This algorithm is off by default.
    It's not used by GEQO anyway.
   </para>
   <para>
    The frontend may be initialized by setting the PGKSQO
    environment variable.
    <variablelist>
     <varlistentry>
      <term>
       QUERY_LIMIT
      </term>
      <listitem>
       <para>
	Sets the number of rows returned by a query.
       </para>
       
       <variablelist>
	<varlistentry>
	 <term>
	  Value
	 </term>
	 <listitem>
	  <para>
	   Maximum number of rows to return for a query.  The default is to allow
	   an unlimited number of rows.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  <replaceable class="parameter">#</replaceable>
	 </term>
	 <listitem>
	  <para>
	   Sets the maximum number of rows returned by a
	   query to <replaceable class="parameter">#</replaceable>.
	  </para>
	 </listitem>
	</varlistentry>
	<varlistentry>
	 <term>
	  DEFAULT
	 </term>
	 <listitem>
	  <para>
	   Sets the maximum number of rows returned by a query to be unlimited.
	  </para>
	 </listitem>
	</varlistentry>
       </variablelist>
       <para>
	By default, there is no limit to the number of rows
	returned by a query.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

    <variablelist>
     <varlistentry>
      <term>
       TRANSACTION ISOLATION LEVEL
      </term>
      <listitem>
       <para>
	Sets the isolation level for the current transaction.
	
	<variablelist>
	 <varlistentry>
	  <term>
	   <replaceable class="parameter">value</replaceable>
	  </term>
	  <listitem>
	   <para>
		Sets the isolation level for the current transaction to
		'SERIALIZABLE' or 'READ COMMITTED'.
	   </para>
	  </listitem>
	 </varlistentry>
   </para>
	 
	 <varlistentry>
	  <term>
	   DEFAULT
	  </term>
	  <listitem>
	   <para>
		Sets the isolation level for the current transaction to
		'SERIALIZABLE' or 'READ COMMITTED'.
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
       </para>

    <variablelist>
     <varlistentry>
      <term>
       CLIENT_ENCODING | NAMES
      </term>
      <listitem>
       <para>
	Sets the multi-byte client encoding
	
	<variablelist>
	 <varlistentry>
	  <term>
	   <replaceable class="parameter">value</replaceable>
	  </term>
	  <listitem>
	   <para>
		Sets the multi-byte client encoding.
	   </para>
	  </listitem>
	 </varlistentry>
   </para>
	 
	 <varlistentry>
	  <term>
	   DEFAULT
	  </term>
	  <listitem>
	   <para>
		Sets the multi-byte client encoding.
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
       </para>
       <para>
	This is only enabled if multi-byte was specified to configure.
       </para>

    <variablelist>
     <varlistentry>
      <term>
       SERVER_ENCODING
      </term>
      <listitem>
       <para>
	Sets the multi-byte server encoding
	
	<variablelist>
	 <varlistentry>
	  <term>
	   <replaceable class="parameter">value</replaceable>
	  </term>
	  <listitem>
	   <para>
		Sets the multi-byte server encoding.
	   </para>
	  </listitem>
	 </varlistentry>
   </para>
	 
	 <varlistentry>
	  <term>
	   DEFAULT
	  </term>
	  <listitem>
	   <para>
		Sets the multi-byte server encoding.
	   </para>
	  </listitem>
	 </varlistentry>
	</variablelist>
       </para>
       <para>
	This is only enabled if multi-byte was specified to configure.
       </para>



  </REFSECT2>
  
  <REFSECT2 ID="R2-SQL-SET-2">
   <REFSECT2INFO>
    <DATE>1998-09-24</DATE>
   </REFSECT2INFO>
   <TITLE>
    Outputs
   </TITLE>
   <PARA>
    
    <VARIABLELIST>
     <VARLISTENTRY>
      <TERM>
       <returnvalue>SET VARIABLE</returnvalue>
      </TERM>
      <LISTITEM>
       <PARA>
	Message returned if successfully.
       </para>
      </listitem>
     </varlistentry>
     
     <VARLISTENTRY>
      <TERM>
       <returnvalue>WARN:  Bad value for <replaceable class="parameter">variable</replaceable> (<replaceable class="parameter">value</replaceable>)</returnvalue>
      </TERM>
      <LISTITEM>
       <PARA>
	If the command fails to set variable.
       </para>
      </listitem>
     </varlistentry>
     
    </VARIABLELIST>
   </para>
  </REFSECT2>
 </REFSYNOPSISDIV>
 
 <REFSECT1 ID="R1-SQL-SET-1">
  <REFSECT1INFO>
   <DATE>1998-09-24</DATE>
  </REFSECT1INFO>
  <TITLE>
   Description
  </TITLE>
  <PARA>
   <command>SET</command> will modify configuration parameters for variable during
   a session.
  </para>
  <para>
   Current values can be obtained using <command>SHOW</command>, and values
   can be restored to the defaults using <command>RESET</command>.
   Parameters and values are case-insensitive. Note that the value
   field is always specified as a string, so is enclosed in
   single-quotes.
  </para>
  <para>
   <command>SET TIME ZONE</command> changes the session's
   default time zone offset.
   A SQL-session always begins with an initial default time zone
   offset.
   The <command>SET TIME ZONE</command> statement is used to change the default
   time zone offset for the current SQL session.
  </para>
  
  <REFSECT2 ID="R2-SQL-SET-3">
   <REFSECT2INFO>
    <DATE>1998-09-24</DATE>
   </REFSECT2INFO>
   <TITLE>
    Notes
   </TITLE>
   <PARA>
    The <command>SET <replaceable class="parameter">variable</replaceable></command>
    statement is a <productname>Postgres</productname> language extension.
   </para>
   <para>
    Refer to <command>SHOW</command> and <command>RESET</command> to 
    display or reset the current values.
   </para>
  </REFSECT2>
 </REFSECT1>
 
 <REFSECT1 ID="R1-SQL-SET-2">
  <TITLE>
   Usage
  </TITLE>
  <PARA>
  </PARA>
  <ProgramListing>
   --Set the style of date to ISO:
   --
   SET DATESTYLE TO 'ISO';
  </programlisting>
  <programlisting> 
   --Enable GEQO for queries with 4 or more tables
   --
   SET GEQO ON=4;
  </programlisting>
  <programlisting> 
   --Set GEQO to default:
   --
   SET GEQO = DEFAULT;
  </programlisting>
  <programlisting> 
   --set the timezone for Berkeley, California:
   SET TIME ZONE 'PST8PDT';
   
   SELECT CURRENT_TIMESTAMP AS today;
   
   today
   ----------------------
   1998-03-31 07:41:21-08
  </programlisting>
  <programlisting> 
   --set the timezone for Italy:
   SET TIME ZONE 'Europe/Rome';
   
   SELECT CURRENT_TIMESTAMP AS today;
   
   today
   ----------------------
   1998-03-31 17:41:31+02
  </ProgramListing>
  
 </REFSECT1>

 <REFSECT1 ID="R1-SQL-SET-3">
  <TITLE>
   Compatibility
  </TITLE>
  <PARA>
  </PARA>
  
  <REFSECT2 ID="R2-SQL-SET-4">
   <REFSECT2INFO>
    <DATE>1998-09-24</DATE>
   </REFSECT2INFO>
   <TITLE>
    SQL92
   </TITLE>
   <PARA>
    There is no
    <command>SET <replaceable class="parameter">variable</replaceable></command>
    in <acronym>SQL92</acronym>.
    
    The <acronym>SQL92</acronym> syntax for <command>SET TIME ZONE</command>
    is slightly different,
    allowing only a single integer value for time zone specification:
    
    <programlisting>
     SET TIME ZONE { interval_value_expression | LOCAL }
    </programlisting>
   </para>
  </refsect2>
 </refsect1>
</REFENTRY>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->