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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_sequence.sgml,v 1.21 2001/11/17 22:20:34 tgl Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="SQL-CREATESEQUENCE">
   7  <refmeta>
   8   <refentrytitle id="sql-createsequence-title">
   9    CREATE SEQUENCE
  10   </refentrytitle>
  11   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  12  </refmeta>
  13  <refnamediv>
  14   <refname>
  15    CREATE SEQUENCE
  16   </refname>
  17   <refpurpose>
  18    define a new sequence generator
  19   </refpurpose>
  20  </refnamediv>
  21  <refsynopsisdiv>
  22   <refsynopsisdivinfo>
  23    <date>1999-07-20</date>
  24   </refsynopsisdivinfo>
  25   <synopsis>
  26 CREATE [ TEMPORARY | TEMP ] SEQUENCE <replaceable class="parameter">seqname</replaceable> [ INCREMENT <replaceable class="parameter">increment</replaceable> ]
  27     [ MINVALUE <replaceable class="parameter">minvalue</replaceable> ] [ MAXVALUE <replaceable class="parameter">maxvalue</replaceable> ]
  28     [ START <replaceable class="parameter">start</replaceable> ] [ CACHE <replaceable class="parameter">cache</replaceable> ] [ CYCLE ]
  29   </synopsis>
  30
  31   <refsect2 id="R2-SQL-CREATESEQUENCE-1">
  32    <refsect2info>
  33     <date>1998-09-11</date>
  34    </refsect2info>
  35    <title>
  36     Inputs
  37    </title>
  38    <para>
  39
  40     <variablelist>
  41      <varlistentry>
  42       <term>TEMPORARY or TEMP</term>
  43       <listitem>
  44        <para>
  45         If specified, the sequence object is created only for this session,
  46         and is automatically dropped on session exit.
  47         Existing permanent sequences with the same name are not visible
  48         (in this session) while the temporary sequence exists.
  49        </para>
  50       </listitem>
  51      </varlistentry>
  52
  53      <varlistentry>
  54       <term><replaceable class="parameter">seqname</replaceable></term>
  55       <listitem>
  56        <para>
  57         The name of a sequence to be created.
  58        </para>
  59       </listitem>
  60      </varlistentry>
  61
  62      <varlistentry>
  63       <term><replaceable class="parameter">increment</replaceable></term>
  64       <listitem>
  65        <para>
  66         The
  67         <option>INCREMENT <replaceable class="parameter">increment</replaceable></option>
  68         clause is optional. A positive value will make an
  69         ascending sequence, a negative one a descending sequence.
  70         The default value is one (1).
  71        </para>
  72       </listitem>
  73      </varlistentry>
  74
  75      <varlistentry>
  76       <term><replaceable class="parameter">minvalue</replaceable></term>
  77       <listitem>
  78        <para>
  79         The optional clause <option>MINVALUE
  80          <replaceable class="parameter">minvalue</replaceable></option>
  81         determines the minimum value
  82         a sequence can generate. The defaults are 1 and -2^63-1 for
  83         ascending and descending sequences, respectively.
  84        </para>
  85       </listitem>
  86      </varlistentry>
  87
  88      <varlistentry>
  89       <term><replaceable class="parameter">maxvalue</replaceable></term>
  90       <listitem>
  91        <para>
  92         The optional clause <option>MAXVALUE
  93          <replaceable class="parameter">maxvalue</replaceable></option>
  94         determines the maximum
  95         value for the sequence. The defaults are 2^63-1 and -1 for
  96         ascending and descending sequences, respectively.
  97        </para>
  98       </listitem>
  99      </varlistentry>
 100
 101      <varlistentry>
 102       <term><replaceable class="parameter">start</replaceable></term>
 103       <listitem>
 104        <para>
 105         The optional <option>START
 106          <replaceable class="parameter">start</replaceable>
 107          clause</option> enables the sequence to begin anywhere.
 108         The default starting value is
 109         <replaceable class="parameter">minvalue</replaceable>
 110         for ascending sequences and
 111         <replaceable class="parameter">maxvalue</replaceable>
 112         for descending ones.
 113        </para>
 114       </listitem>
 115      </varlistentry>
 116
 117      <varlistentry>
 118       <term><replaceable class="parameter">cache</replaceable></term>
 119       <listitem>
 120        <para>
 121         The <option>CACHE <replaceable class="parameter">cache</replaceable></option> option
 122         enables sequence numbers to be preallocated
 123         and stored in memory for faster access. The  minimum
 124         value is 1 (only one value can be generated at a time, i.e., no cache)
 125         and this is also the default.
 126        </para>
 127       </listitem>
 128      </varlistentry>
 129
 130      <varlistentry>
 131       <term>CYCLE</term>
 132       <listitem>
 133        <para>
 134         The optional CYCLE keyword may be used to enable the sequence
 135         to wrap around when the
 136         <replaceable class="parameter">maxvalue</replaceable> or
 137         <replaceable class="parameter">minvalue</replaceable> has been
 138         reached by
 139         an ascending or descending sequence respectively. If the limit is
 140         reached, the next number generated will be the
 141         <replaceable class="parameter">minvalue</replaceable> or
 142         <replaceable class="parameter">maxvalue</replaceable>,
 143         respectively.
 144         Without CYCLE, after the limit is reached <function>nextval</> calls
 145         will return an error.
 146        </para>
 147       </listitem>
 148      </varlistentry>
 149     </variablelist>
 150    </para>
 151   </refsect2>
 152
 153   <refsect2 id="R2-SQL-CREATESEQUENCE-2">
 154    <refsect2info>
 155     <date>1998-09-11</date>
 156    </refsect2info>
 157    <title>
 158     Outputs
 159    </title>
 160    <para>
 161
 162     <variablelist>
 163      <varlistentry>
 164       <term><computeroutput>
 165 CREATE
 166        </computeroutput></term>
 167       <listitem>
 168        <para>
 169         Message returned if the command is successful.
 170        </para>
 171       </listitem>
 172      </varlistentry>
 173      <varlistentry>
 174       <term><computeroutput>
 175 ERROR:  Relation '<replaceable class="parameter">seqname</replaceable>' already exists
 176        </computeroutput></term>
 177       <listitem>
 178        <para>
 179         If the sequence specified already exists.
 180        </para>
 181       </listitem>
 182      </varlistentry>
 183      <varlistentry>
 184       <term><computeroutput>
 185 ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
 186        </computeroutput></term>
 187       <listitem>
 188        <para>
 189         If the specified starting value is out of range.
 190        </para>
 191       </listitem>
 192      </varlistentry>
 193      <varlistentry>
 194       <term><computeroutput>
 195 ERROR:  DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)
 196        </computeroutput></term>
 197       <listitem>
 198        <para>
 199         If the specified starting value is out of range.
 200        </para>
 201       </listitem>
 202      </varlistentry>
 203      <varlistentry>
 204       <term><computeroutput>
 205 ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
 206        </computeroutput></term>
 207       <listitem>
 208        <para>
 209         If the minimum and maximum values are inconsistent.
 210        </para>
 211       </listitem>
 212      </varlistentry>
 213     </variablelist>
 214    </para>
 215   </refsect2>
 216  </refsynopsisdiv>
 217
 218  <refsect1 id="R1-SQL-CREATESEQUENCE-1">
 219   <refsect1info>
 220    <date>1998-09-11</date>
 221   </refsect1info>
 222   <title>
 223    Description
 224   </title>
 225   <para>
 226    <command>CREATE SEQUENCE</command> will enter a new sequence number generator
 227    into the current database. This involves creating and initializing a
 228    new single-row
 229    table with the name <replaceable class="parameter">seqname</replaceable>.
 230    The generator will be owned by the user issuing the command.
 231   </para>
 232
 233   <para>
 234    After a sequence is created, you use the functions
 235    <function>nextval</function>,
 236    <function>currval</function> and
 237    <function>setval</function>
 238    to operate on the sequence.  These functions are documented in
 239    the <citetitle>User's Guide</citetitle>.
 240   </para>
 241
 242   <para>
 243    Although you cannot update a sequence directly, you can use a query like
 244
 245    <programlisting>
 246 SELECT * FROM <replaceable>seqname</replaceable>;
 247    </programlisting>
 248
 249    to examine the parameters and current state of a sequence.  In particular,
 250    the <literal>last_value</> field of the sequence shows the last value
 251    allocated by any backend process.  (Of course, this value may be obsolete
 252    by the time it's printed, if other processes are actively doing
 253    <function>nextval</> calls.)
 254   </para>
 255
 256   <caution>
 257    <para>
 258     Unexpected results may be obtained if a <replaceable class="parameter">cache</replaceable> setting greater than one
 259     is used for a sequence object that will be used concurrently by multiple
 260     backends.  Each backend will allocate and cache successive sequence values
 261     during one access to the sequence object and increase the sequence
 262     object's <literal>last_value</> accordingly.  Then, the next <replaceable class="parameter">cache</replaceable>-1 uses of <function>nextval</>
 263     within that backend simply return the preallocated values without touching
 264     the shared object.  So, any numbers allocated but not used within a session
 265     will be lost when that session ends.  Furthermore, although multiple backends are guaranteed to
 266     allocate distinct sequence values, the values may be generated out of
 267     sequence when all the backends are considered.  (For example, with a <replaceable class="parameter">cache</replaceable>
 268     setting of 10, backend A might reserve values 1..10 and return nextval=1,
 269     then
 270     backend B might reserve values 11..20 and return nextval=11 before backend
 271     A has generated nextval=2.)  Thus, with a <replaceable class="parameter">cache</replaceable> setting of one it is safe
 272     to assume that <function>nextval</> values are generated sequentially; with a <replaceable class="parameter">cache</replaceable>
 273     setting greater than one you should only assume that the <function>nextval</> values
 274     are all distinct, not that they are generated purely sequentially.
 275     Also, <literal>last_value</> will reflect the latest value reserved by any backend,
 276     whether or not it has yet been returned by <function>nextval</>.
 277     Another consideration is that a <function>setval</> executed on such a sequence
 278     will not be noticed by other backends until they have used up any
 279     preallocated values they have cached.
 280    </para>
 281   </caution>
 282
 283   <refsect2 id="R2-SQL-CREATESEQUENCE-3">
 284    <refsect2info>
 285     <date>1998-09-11</date>
 286    </refsect2info>
 287    <title>
 288     Notes
 289    </title>
 290    <para>
 291     Use <command>DROP SEQUENCE</command> to remove a sequence.
 292    </para>
 293    <para>
 294     When <replaceable class="parameter">cache</replaceable> is greater than
 295     one, each backend uses its own cache to store preallocated numbers.
 296     Numbers that are cached but not used in the current session will be
 297     lost, resulting in <quote>holes</quote> in the sequence.
 298    </para>
 299   </refsect2>
 300  </refsect1>
 301
 302  <refsect1 id="R1-SQL-CREATESEQUENCE-2">
 303   <title>
 304    Usage
 305   </title>
 306   <para>
 307    Create an ascending sequence called <literal>serial</literal>, starting at 101:
 308   </para>
 309   <programlisting>
 310 CREATE SEQUENCE serial START 101;
 311   </programlisting>
 312   <para>
 313    Select the next number from this sequence:
 314    <programlisting>
 315 SELECT nextval('serial');
 316
 317 nextval
 318 -------
 319     114
 320    </programlisting>
 321   </para>
 322   <para>
 323    Use this sequence in an INSERT:
 324    <programlisting>
 325 INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
 326    </programlisting>
 327   </para>
 328
 329   <para>
 330    Update the sequence value after a COPY FROM:
 331    <programlisting>
 332 BEGIN;
 333     COPY distributors FROM 'input_file';
 334     SELECT setval('serial', max(id)) FROM distributors;
 335 END;
 336    </programlisting>
 337   </para>
 338  </refsect1>
 339
 340  <refsect1 id="R1-SQL-CREATESEQUENCE-3">
 341   <title>
 342    Compatibility
 343   </title>
 344
 345   <refsect2 id="R2-SQL-CREATESEQUENCE-4">
 346    <refsect2info>
 347     <date>1998-09-11</date>
 348    </refsect2info>
 349    <title>
 350     SQL92
 351    </title>
 352
 353    <para>
 354     <command>CREATE SEQUENCE</command> is a <productname>Postgres</productname>
 355     language extension.
 356     There is no <command>CREATE SEQUENCE</command> statement
 357     in <acronym>SQL92</acronym>.
 358    </para>
 359   </refsect2>
 360  </refsect1>
 361 </refentry>
 362
 363 <!-- Keep this comment at the end of the file
 364 Local variables:
 365 mode: sgml
 366 sgml-omittag:nil
 367 sgml-shorttag:t
 368 sgml-minimize-attributes:nil
 369 sgml-always-quote-attributes:t
 370 sgml-indent-step:1
 371 sgml-indent-data:t
 372 sgml-parent-document:nil
 373 sgml-default-dtd-file:"../reference.ced"
 374 sgml-exposed-tags:nil
 375 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 376 sgml-local-ecat-files:nil
 377 End:
 378 -->