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