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.24 2002/01/20 22:19:56 petere Exp $
   3 PostgreSQL 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 <function>nextval</function>=1,
 269     then
 270     backend B might reserve values 11..20 and return <function>nextval</function>=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
 291    <para>
 292     Use <command>DROP SEQUENCE</command> to remove a sequence.
 293    </para>
 294
 295    <para>
 296     Sequences are based on <type>bigint</> arithmetic, so the range cannot
 297     exceed the range of an eight-byte integer
 298     (-9223372036854775808 to 9223372036854775807).  On some older platforms,
 299     there may be no compiler support for eight-byte integers, in which case
 300     sequences use regular <type>integer</> arithmetic (range
 301     -2147483648 to +2147483647).
 302    </para>
 303
 304    <para>
 305     When <replaceable class="parameter">cache</replaceable> is greater than
 306     one, each backend uses its own cache to store preallocated numbers.
 307     Numbers that are cached but not used in the current session will be
 308     lost, resulting in <quote>holes</quote> in the sequence.
 309    </para>
 310   </refsect2>
 311  </refsect1>
 312
 313  <refsect1 id="R1-SQL-CREATESEQUENCE-2">
 314   <title>
 315    Usage
 316   </title>
 317   <para>
 318    Create an ascending sequence called <literal>serial</literal>, starting at 101:
 319   </para>
 320   <programlisting>
 321 CREATE SEQUENCE serial START 101;
 322   </programlisting>
 323   <para>
 324    Select the next number from this sequence:
 325    <programlisting>
 326 SELECT nextval('serial');
 327
 328 nextval
 329 -------
 330     114
 331    </programlisting>
 332   </para>
 333   <para>
 334    Use this sequence in an INSERT:
 335    <programlisting>
 336 INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
 337    </programlisting>
 338   </para>
 339
 340   <para>
 341    Update the sequence value after a COPY FROM:
 342    <programlisting>
 343 BEGIN;
 344     COPY distributors FROM 'input_file';
 345     SELECT setval('serial', max(id)) FROM distributors;
 346 END;
 347    </programlisting>
 348   </para>
 349  </refsect1>
 350
 351  <refsect1 id="R1-SQL-CREATESEQUENCE-3">
 352   <title>
 353    Compatibility
 354   </title>
 355
 356   <refsect2 id="R2-SQL-CREATESEQUENCE-4">
 357    <refsect2info>
 358     <date>1998-09-11</date>
 359    </refsect2info>
 360    <title>
 361     SQL92
 362    </title>
 363
 364    <para>
 365     <command>CREATE SEQUENCE</command> is a <productname>PostgreSQL</productname>
 366     language extension.
 367     There is no <command>CREATE SEQUENCE</command> statement
 368     in <acronym>SQL92</acronym>.
 369    </para>
 370   </refsect2>
 371  </refsect1>
 372 </refentry>
 373
 374 <!-- Keep this comment at the end of the file
 375 Local variables:
 376 mode: sgml
 377 sgml-omittag:nil
 378 sgml-shorttag:t
 379 sgml-minimize-attributes:nil
 380 sgml-always-quote-attributes:t
 381 sgml-indent-step:1
 382 sgml-indent-data:t
 383 sgml-parent-document:nil
 384 sgml-default-dtd-file:"../reference.ced"
 385 sgml-exposed-tags:nil
 386 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 387 sgml-local-ecat-files:nil
 388 End:
 389 -->