begriffs open source - ai-pg/blob - full-docs/src/sgml/html/sql-set.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>SET</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-selectinto.html" title="SELECT INTO" /><link rel="next" href="sql-set-constraints.html" title="SET CONSTRAINTS" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">SET</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-selectinto.html" title="SELECT INTO">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-set-constraints.html" title="SET CONSTRAINTS">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-SET"><div class="titlepage"></div><a id="id-1.9.3.174.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">SET</span></h2><p>SET — change a run-time parameter</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 SET [ SESSION | LOCAL ] <em class="replaceable"><code>configuration_parameter</code></em> { TO | = } { <em class="replaceable"><code>value</code></em> | '<em class="replaceable"><code>value</code></em>' | DEFAULT }
   4 SET [ SESSION | LOCAL ] TIME ZONE { <em class="replaceable"><code>value</code></em> | '<em class="replaceable"><code>value</code></em>' | LOCAL | DEFAULT }
   5 </pre></div><div class="refsect1" id="id-1.9.3.174.5"><h2>Description</h2><p>
   6    The <code class="command">SET</code> command changes run-time configuration
   7    parameters.  Many of the run-time parameters listed in
   8    <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a> can be changed on-the-fly with
   9    <code class="command">SET</code>.
  10    (Some parameters can only be changed by superusers and users who
  11    have been granted <code class="literal">SET</code> privilege on that parameter.
  12    There are also parameters that cannot be changed after server or
  13    session start.)
  14    <code class="command">SET</code> only affects the value used by the current
  15    session.
  16   </p><p>
  17    If <code class="command">SET</code> (or equivalently <code class="command">SET SESSION</code>)
  18    is issued within a transaction that is later aborted, the effects of the
  19    <code class="command">SET</code> command disappear when the transaction is rolled
  20    back.  Once the surrounding transaction is committed, the effects
  21    will persist until the end of the session, unless overridden by another
  22    <code class="command">SET</code>.
  23   </p><p>
  24    The effects of <code class="command">SET LOCAL</code> last only till the end of
  25    the current transaction, whether committed or not.  A special case is
  26    <code class="command">SET</code> followed by <code class="command">SET LOCAL</code> within
  27    a single transaction: the <code class="command">SET LOCAL</code> value will be
  28    seen until the end of the transaction, but afterwards (if the transaction
  29    is committed) the <code class="command">SET</code> value will take effect.
  30   </p><p>
  31    The effects of <code class="command">SET</code> or <code class="command">SET LOCAL</code> are
  32    also canceled by rolling back to a savepoint that is earlier than the
  33    command.
  34   </p><p>
  35    If <code class="command">SET LOCAL</code> is used within a function that has a
  36    <code class="literal">SET</code> option for the same variable (see
  37    <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>),
  38    the effects of the <code class="command">SET LOCAL</code> command disappear at
  39    function exit; that is, the value in effect when the function was called is
  40    restored anyway.  This allows <code class="command">SET LOCAL</code> to be used for
  41    dynamic or repeated changes of a parameter within a function, while still
  42    having the convenience of using the <code class="literal">SET</code> option to save and
  43    restore the caller's value.  However, a regular <code class="command">SET</code> command
  44    overrides any surrounding function's <code class="literal">SET</code> option; its effects
  45    will persist unless rolled back.
  46   </p><div class="note"><h3 class="title">Note</h3><p>
  47     In <span class="productname">PostgreSQL</span> versions 8.0 through 8.2,
  48     the effects of a <code class="command">SET LOCAL</code> would be canceled by
  49     releasing an earlier savepoint, or by successful exit from a
  50     <span class="application">PL/pgSQL</span> exception block.  This behavior
  51     has been changed because it was deemed unintuitive.
  52    </p></div></div><div class="refsect1" id="id-1.9.3.174.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SESSION</code></span></dt><dd><p>
  53       Specifies that the command takes effect for the current session.
  54       (This is the default if neither <code class="literal">SESSION</code> nor
  55       <code class="literal">LOCAL</code> appears.)
  56      </p></dd><dt><span class="term"><code class="literal">LOCAL</code></span></dt><dd><p>
  57       Specifies that the command takes effect for only the current
  58       transaction.  After <code class="command">COMMIT</code> or <code class="command">ROLLBACK</code>,
  59       the session-level setting takes effect again.  Issuing this
  60       outside of a transaction block emits a warning and otherwise has
  61       no effect.
  62      </p></dd><dt><span class="term"><em class="replaceable"><code>configuration_parameter</code></em></span></dt><dd><p>
  63       Name of a settable run-time parameter.  Available parameters are
  64       documented in <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a> and below.
  65      </p></dd><dt><span class="term"><em class="replaceable"><code>value</code></em></span></dt><dd><p>
  66       New value of parameter.  Values can be specified as string
  67       constants, identifiers, numbers, or comma-separated lists of
  68       these, as appropriate for the particular parameter.
  69       <code class="literal">DEFAULT</code> can be written to specify
  70       resetting the parameter to its default value (that is, whatever
  71       value it would have had if no <code class="command">SET</code> had been executed
  72       in the current session).
  73      </p></dd></dl></div><p>
  74    Besides the configuration parameters documented in <a class="xref" href="runtime-config.html" title="Chapter 19. Server Configuration">Chapter 19</a>, there are a few that can only be
  75    adjusted using the <code class="command">SET</code> command or that have a
  76    special syntax:
  77
  78    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">SCHEMA</code></span></dt><dd><p><code class="literal">SET SCHEMA '<em class="replaceable"><code>value</code></em>'</code> is an alias for
  79        <code class="literal">SET search_path TO <em class="replaceable"><code>value</code></em></code>.  Only one
  80        schema can be specified using this syntax.
  81       </p></dd><dt><span class="term"><code class="literal">NAMES</code></span></dt><dd><p><code class="literal">SET NAMES '<em class="replaceable"><code>value</code></em>'</code> is an alias for
  82        <code class="literal">SET client_encoding TO <em class="replaceable"><code>value</code></em></code>.
  83       </p></dd><dt><span class="term"><code class="literal">SEED</code></span></dt><dd><p>
  84        Sets the internal seed for the random number generator (the
  85        function <code class="function">random</code>).  Allowed values are
  86        floating-point numbers between -1 and 1 inclusive.
  87       </p><p>
  88        The seed can also be set by invoking the function
  89        <code class="function">setseed</code>:
  90 </p><pre class="programlisting">
  91 SELECT setseed(<em class="replaceable"><code>value</code></em>);
  92 </pre></dd><dt><span class="term"><code class="literal">TIME ZONE</code></span></dt><dd><p><code class="literal">SET TIME ZONE '<em class="replaceable"><code>value</code></em>'</code> is an alias
  93        for <code class="literal">SET timezone TO '<em class="replaceable"><code>value</code></em>'</code>.  The
  94        syntax <code class="literal">SET TIME ZONE</code> allows special syntax
  95        for the time zone specification.  Here are examples of valid
  96        values:
  97
  98        </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">'America/Los_Angeles'</code></span></dt><dd><p>
  99            The time zone for Berkeley, California.
 100           </p></dd><dt><span class="term"><code class="literal">'Europe/Rome'</code></span></dt><dd><p>
 101            The time zone for Italy.
 102           </p></dd><dt><span class="term"><code class="literal">-7</code></span></dt><dd><p>
 103            The time zone 7 hours west from UTC (equivalent
 104            to PDT).  Positive values are east from UTC.
 105           </p></dd><dt><span class="term"><code class="literal">INTERVAL '-08:00' HOUR TO MINUTE</code></span></dt><dd><p>
 106            The time zone 8 hours west from UTC (equivalent
 107            to PST).
 108           </p></dd><dt><span class="term"><code class="literal">LOCAL</code><br /></span><span class="term"><code class="literal">DEFAULT</code></span></dt><dd><p>
 109            Set the time zone to your local time zone (that is, the
 110            server's default value of <code class="varname">timezone</code>).
 111           </p></dd></dl></div><p>
 112       </p><p>
 113        Timezone settings given as numbers or intervals are internally
 114        translated to POSIX timezone syntax.  For example, after
 115        <code class="literal">SET TIME ZONE -7</code>, <code class="command">SHOW TIME ZONE</code> would
 116        report <code class="literal">&lt;-07&gt;+07</code>.
 117       </p><p>
 118        Time zone abbreviations are not supported by <code class="command">SET</code>;
 119        see <a class="xref" href="datatype-datetime.html#DATATYPE-TIMEZONES" title="8.5.3. Time Zones">Section 8.5.3</a> for more information
 120        about time zones.
 121       </p></dd></dl></div><p>
 122   </p></div><div class="refsect1" id="id-1.9.3.174.7"><h2>Notes</h2><p>
 123    The function <code class="function">set_config</code> provides equivalent
 124    functionality; see <a class="xref" href="functions-admin.html#FUNCTIONS-ADMIN-SET" title="9.28.1. Configuration Settings Functions">Section 9.28.1</a>.
 125    Also, it is possible to UPDATE the
 126    <a class="link" href="view-pg-settings.html" title="53.25. pg_settings"><code class="structname">pg_settings</code></a>
 127    system view to perform the equivalent of <code class="command">SET</code>.
 128   </p></div><div class="refsect1" id="id-1.9.3.174.8"><h2>Examples</h2><p>
 129    Set the schema search path:
 130 </p><pre class="programlisting">
 131 SET search_path TO my_schema, public;
 132 </pre><p>
 133   </p><p>
 134    Set the style of date to traditional
 135    <span class="productname">POSTGRES</span> with <span class="quote">“<span class="quote">day before month</span>”</span>
 136    input convention:
 137 </p><pre class="screen">
 138 SET datestyle TO postgres, dmy;
 139 </pre><p>
 140   </p><p>
 141    Set the time zone for Berkeley, California:
 142 </p><pre class="screen">
 143 SET TIME ZONE 'America/Los_Angeles';
 144 </pre><p>
 145   </p><p>
 146    Set the time zone for Italy:
 147 </p><pre class="screen">
 148 SET TIME ZONE 'Europe/Rome';
 149 </pre></div><div class="refsect1" id="id-1.9.3.174.9"><h2>Compatibility</h2><p>
 150    <code class="literal">SET TIME ZONE</code> extends syntax defined in the SQL
 151    standard.  The standard allows only numeric time zone offsets while
 152    <span class="productname">PostgreSQL</span> allows more flexible
 153    time-zone specifications.  All other <code class="literal">SET</code>
 154    features are <span class="productname">PostgreSQL</span> extensions.
 155   </p></div><div class="refsect1" id="id-1.9.3.174.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="sql-reset.html" title="RESET"><span class="refentrytitle">RESET</span></a>, <a class="xref" href="sql-show.html" title="SHOW"><span class="refentrytitle">SHOW</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-selectinto.html" title="SELECT INTO">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-set-constraints.html" title="SET CONSTRAINTS">Next</a></td></tr><tr><td width="40%" align="left" valign="top">SELECT INTO </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> SET CONSTRAINTS</td></tr></table></div></body></html>