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