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.19 2001/09/03 12:57:49 petere 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
  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 is created only for this session, and is
  46         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        </para>
 145       </listitem>
 146      </varlistentry>
 147     </variablelist>
 148    </para>
 149   </refsect2>
 150
 151   <refsect2 id="R2-SQL-CREATESEQUENCE-2">
 152    <refsect2info>
 153     <date>1998-09-11</date>
 154    </refsect2info>
 155    <title>
 156     Outputs
 157    </title>
 158    <para>
 159
 160     <variablelist>
 161      <varlistentry>
 162       <term><computeroutput>
 163 CREATE
 164        </computeroutput></term>
 165       <listitem>
 166        <para>
 167         Message returned if the command is successful.
 168        </para>
 169       </listitem>
 170      </varlistentry>
 171      <varlistentry>
 172       <term><computeroutput>
 173 ERROR:  Relation '<replaceable class="parameter">seqname</replaceable>' already exists
 174        </computeroutput></term>
 175       <listitem>
 176        <para>
 177         If the sequence specified already exists.
 178        </para>
 179       </listitem>
 180      </varlistentry>
 181      <varlistentry>
 182       <term><computeroutput>
 183 ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">start</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
 184        </computeroutput></term>
 185       <listitem>
 186        <para>
 187         If the specified starting value is out of range.
 188        </para>
 189       </listitem>
 190      </varlistentry>
 191      <varlistentry>
 192       <term><computeroutput>
 193 ERROR:  DefineSequence: START value (<replaceable class="parameter">start</replaceable>) can't be < MINVALUE (<replaceable class="parameter">min</replaceable>)
 194        </computeroutput></term>
 195       <listitem>
 196        <para>
 197         If the specified starting value is out of range.
 198        </para>
 199       </listitem>
 200      </varlistentry>
 201      <varlistentry>
 202       <term><computeroutput>
 203 ERROR:  DefineSequence: MINVALUE (<replaceable class="parameter">min</replaceable>) can't be >= MAXVALUE (<replaceable class="parameter">max</replaceable>)
 204        </computeroutput></term>
 205       <listitem>
 206        <para>
 207         If the minimum and maximum values are inconsistent.
 208        </para>
 209       </listitem>
 210      </varlistentry>
 211     </variablelist>
 212    </para>
 213   </refsect2>
 214  </refsynopsisdiv>
 215
 216  <refsect1 id="R1-SQL-CREATESEQUENCE-1">
 217   <refsect1info>
 218    <date>1998-09-11</date>
 219   </refsect1info>
 220   <title>
 221    Description
 222   </title>
 223   <para>
 224    <command>CREATE SEQUENCE</command> will enter a new sequence number generator
 225    into the current data base. This involves creating and initializing a
 226    new single-row
 227    table with the name <replaceable class="parameter">seqname</replaceable>.
 228    The generator will be owned by the user issuing the command.
 229   </para>
 230
 231   <para>
 232    After a sequence is created, you may use the function
 233    <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
 234    to get a new number from the sequence.
 235    The function
 236    <function>currval('<replaceable class="parameter">seqname</replaceable>')</function>
 237    may be used to determine the number returned by the last call to
 238    <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
 239    for the specified sequence in the current session.
 240    The function
 241    <function>setval('<replaceable class="parameter">seqname</replaceable>',
 242     <replaceable class="parameter">newvalue</replaceable>)</function>
 243    may be used to set the current value of the specified sequence.
 244    The next call to
 245    <function>nextval('<replaceable class="parameter">seqname</replaceable>')</function>
 246    will return the given value plus the sequence increment.
 247   </para>
 248
 249   <para>
 250    Use a query like
 251
 252    <programlisting>
 253 SELECT * FROM <replaceable>seqname</replaceable>;
 254    </programlisting>
 255
 256    to examine the parameters of a sequence.
 257
 258    As an alternative to fetching the
 259    parameters from the original definition as above, you can use
 260
 261    <programlisting>
 262 SELECT last_value FROM <replaceable>seqname</replaceable>;
 263    </programlisting>
 264
 265    to obtain the last value allocated by any backend.
 266   </para>
 267
 268   <para>
 269    To avoid blocking of concurrent transactions
 270    that obtain numbers from the same sequence, a nextval operation
 271    is never rolled back; that is, once a value has been fetched it is
 272    considered used, even if the transaction that did the nextval later
 273    aborts.  This means that aborted transactions may leave unused "holes"
 274    in the sequence of assigned values.  setval operations are never
 275    rolled back, either.
 276   </para>
 277
 278   <caution>
 279    <para>
 280     Unexpected results may be obtained if a cache setting greater than one
 281     is used for a sequence object that will be used concurrently by multiple
 282     backends.  Each backend will allocate and cache successive sequence values
 283     during one access to the sequence object and increase the sequence
 284     object's last_value accordingly.  Then, the next cache-1 uses of nextval
 285     within that backend simply return the preallocated values without touching
 286     the shared object.  So, numbers allocated but not used in the current session
 287     will be lost.  Furthermore, although multiple backends are guaranteed to
 288     allocate distinct sequence values, the values may be generated out of
 289     sequence when all the backends are considered.  (For example, with a cache
 290     setting of 10, backend A might reserve values 1..10 and return nextval=1,
 291     then
 292     backend B might reserve values 11..20 and return nextval=11 before backend
 293     A has generated nextval=2.)  Thus, with a cache setting of one it is safe
 294     to assume that nextval values are generated sequentially; with a cache
 295     setting greater than one you should only assume that the nextval values
 296     are all distinct, not that they are generated purely sequentially.
 297     Also, last_value will reflect the latest value reserved by any backend,
 298     whether or not it has yet been returned by nextval.
 299     Another consideration is that a setval executed on such a sequence
 300     will not be noticed by other backends until they have used up any
 301     preallocated values they have cached.
 302    </para>
 303   </caution>
 304
 305   <refsect2 id="R2-SQL-CREATESEQUENCE-3">
 306    <refsect2info>
 307     <date>1998-09-11</date>
 308    </refsect2info>
 309    <title>
 310     Notes
 311    </title>
 312    <para>
 313     Use <command>DROP SEQUENCE</command> to remove a sequence.
 314    </para>
 315    <para>
 316     Each backend uses its own cache to store preallocated numbers.
 317     Numbers that are cached but not used in the current session will be
 318     lost, resulting in "holes" in the sequence.
 319    </para>
 320   </refsect2>
 321  </refsect1>
 322
 323  <refsect1 id="R1-SQL-CREATESEQUENCE-2">
 324   <title>
 325    Usage
 326   </title>
 327   <para>
 328    Create an ascending sequence called <literal>serial</literal>, starting at 101:
 329   </para>
 330   <programlisting>
 331 CREATE SEQUENCE serial START 101;
 332   </programlisting>
 333   <para>
 334    Select the next number from this sequence:
 335    <programlisting>
 336 SELECT NEXTVAL ('serial');
 337
 338 nextval
 339 -------
 340     114
 341    </programlisting>
 342   </para>
 343   <para>
 344    Use this sequence in an INSERT:
 345    <programlisting>
 346 INSERT INTO distributors VALUES (NEXTVAL('serial'),'nothing');
 347    </programlisting>
 348   </para>
 349
 350   <para>
 351    Set the sequence value after a COPY FROM:
 352    <programlisting>
 353 CREATE FUNCTION distributors_id_max() RETURNS INT4
 354     AS 'SELECT max(id) FROM distributors'
 355     LANGUAGE 'sql';
 356 BEGIN;
 357     COPY distributors FROM 'input_file';
 358     SELECT setval('serial', distributors_id_max());
 359 END;
 360    </programlisting>
 361   </para>
 362  </refsect1>
 363
 364  <refsect1 id="R1-SQL-CREATESEQUENCE-3">
 365   <title>
 366    Compatibility
 367   </title>
 368
 369   <refsect2 id="R2-SQL-CREATESEQUENCE-4">
 370    <refsect2info>
 371     <date>1998-09-11</date>
 372    </refsect2info>
 373    <title>
 374     SQL92
 375    </title>
 376
 377    <para>
 378     <command>CREATE SEQUENCE</command> is a <productname>Postgres</productname>
 379     language extension.
 380     There is no <command>CREATE SEQUENCE</command> statement
 381     in <acronym>SQL92</acronym>.
 382    </para>
 383   </refsect2>
 384  </refsect1>
 385 </refentry>
 386
 387 <!-- Keep this comment at the end of the file
 388 Local variables:
 389 mode: sgml
 390 sgml-omittag:nil
 391 sgml-shorttag:t
 392 sgml-minimize-attributes:nil
 393 sgml-always-quote-attributes:t
 394 sgml-indent-step:1
 395 sgml-indent-data:t
 396 sgml-parent-document:nil
 397 sgml-default-dtd-file:"../reference.ced"
 398 sgml-exposed-tags:nil
 399 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 400 sgml-local-ecat-files:nil
 401 End:
 402 -->