begriffs open source - ai-pg/blob - full-docs/txt/sql-createsequence.txt

   1
   2 CREATE SEQUENCE
   3
   4    CREATE SEQUENCE — define a new sequence generator
   5
   6 Synopsis
   7
   8 CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] name
   9     [ AS data_type ]
  10     [ INCREMENT [ BY ] increment ]
  11     [ MINVALUE minvalue | NO MINVALUE ] [ MAXVALUE maxvalue | NO MAXVALUE ]
  12     [ [ NO ] CYCLE ]
  13     [ START [ WITH ] start ]
  14     [ CACHE cache ]
  15     [ OWNED BY { table_name.column_name | NONE } ]
  16
  17 Description
  18
  19    CREATE SEQUENCE creates a new sequence number generator. This involves
  20    creating and initializing a new special single-row table with the name
  21    name. The generator will be owned by the user issuing the command.
  22
  23    If a schema name is given then the sequence is created in the specified
  24    schema. Otherwise it is created in the current schema. Temporary
  25    sequences exist in a special schema, so a schema name cannot be given
  26    when creating a temporary sequence. The sequence name must be distinct
  27    from the name of any other relation (table, sequence, index, view,
  28    materialized view, or foreign table) in the same schema.
  29
  30    After a sequence is created, you use the functions nextval, currval,
  31    and setval to operate on the sequence. These functions are documented
  32    in Section 9.17.
  33
  34    Although you cannot update a sequence directly, you can use a query
  35    like:
  36 SELECT * FROM name;
  37
  38    to examine the parameters and current state of a sequence. In
  39    particular, the last_value field of the sequence shows the last value
  40    allocated by any session. (Of course, this value might be obsolete by
  41    the time it's printed, if other sessions are actively doing nextval
  42    calls.)
  43
  44 Parameters
  45
  46    TEMPORARY or TEMP
  47           If specified, the sequence object is created only for this
  48           session, and is automatically dropped on session exit. Existing
  49           permanent sequences with the same name are not visible (in this
  50           session) while the temporary sequence exists, unless they are
  51           referenced with schema-qualified names.
  52
  53    UNLOGGED
  54           If specified, the sequence is created as an unlogged sequence.
  55           Changes to unlogged sequences are not written to the write-ahead
  56           log. They are not crash-safe: an unlogged sequence is
  57           automatically reset to its initial state after a crash or
  58           unclean shutdown. Unlogged sequences are also not replicated to
  59           standby servers.
  60
  61           Unlike unlogged tables, unlogged sequences do not offer a
  62           significant performance advantage. This option is mainly
  63           intended for sequences associated with unlogged tables via
  64           identity columns or serial columns. In those cases, it usually
  65           wouldn't make sense to have the sequence WAL-logged and
  66           replicated but not its associated table.
  67
  68    IF NOT EXISTS
  69           Do not throw an error if a relation with the same name already
  70           exists. A notice is issued in this case. Note that there is no
  71           guarantee that the existing relation is anything like the
  72           sequence that would have been created — it might not even be a
  73           sequence.
  74
  75    name
  76           The name (optionally schema-qualified) of the sequence to be
  77           created.
  78
  79    data_type
  80           The optional clause AS data_type specifies the data type of the
  81           sequence. Valid types are smallint, integer, and bigint. bigint
  82           is the default. The data type determines the default minimum and
  83           maximum values of the sequence.
  84
  85    increment
  86           The optional clause INCREMENT BY increment specifies which value
  87           is added to the current sequence value to create a new value. A
  88           positive value will make an ascending sequence, a negative one a
  89           descending sequence. The default value is 1.
  90
  91    minvalue
  92           NO MINVALUE
  93           The optional clause MINVALUE minvalue determines the minimum
  94           value a sequence can generate. If this clause is not supplied or
  95           NO MINVALUE is specified, then defaults will be used. The
  96           default for an ascending sequence is 1. The default for a
  97           descending sequence is the minimum value of the data type.
  98
  99    maxvalue
 100           NO MAXVALUE
 101           The optional clause MAXVALUE maxvalue determines the maximum
 102           value for the sequence. If this clause is not supplied or NO
 103           MAXVALUE is specified, then default values will be used. The
 104           default for an ascending sequence is the maximum value of the
 105           data type. The default for a descending sequence is -1.
 106
 107    CYCLE
 108           NO CYCLE
 109           The CYCLE option allows the sequence to wrap around when the
 110           maxvalue or minvalue has been reached by an ascending or
 111           descending sequence respectively. If the limit is reached, the
 112           next number generated will be the minvalue or maxvalue,
 113           respectively.
 114
 115           If NO CYCLE is specified, any calls to nextval after the
 116           sequence has reached its maximum value will return an error. If
 117           neither CYCLE or NO CYCLE are specified, NO CYCLE is the
 118           default.
 119
 120    start
 121           The optional clause START WITH start allows the sequence to
 122           begin anywhere. The default starting value is minvalue for
 123           ascending sequences and maxvalue for descending ones.
 124
 125    cache
 126           The optional clause CACHE cache specifies how many sequence
 127           numbers are to be preallocated and stored in memory for faster
 128           access. The minimum value is 1 (only one value can be generated
 129           at a time, i.e., no cache), and this is also the default.
 130
 131    OWNED BY table_name.column_name
 132           OWNED BY NONE
 133           The OWNED BY option causes the sequence to be associated with a
 134           specific table column, such that if that column (or its whole
 135           table) is dropped, the sequence will be automatically dropped as
 136           well. The specified table must have the same owner and be in the
 137           same schema as the sequence. OWNED BY NONE, the default,
 138           specifies that there is no such association.
 139
 140 Notes
 141
 142    Use DROP SEQUENCE to remove a sequence.
 143
 144    Sequences are based on bigint arithmetic, so the range cannot exceed
 145    the range of an eight-byte integer (-9223372036854775808 to
 146    9223372036854775807).
 147
 148    Because nextval and setval calls are never rolled back, sequence
 149    objects cannot be used if “gapless” assignment of sequence numbers is
 150    needed. It is possible to build gapless assignment by using exclusive
 151    locking of a table containing a counter; but this solution is much more
 152    expensive than sequence objects, especially if many transactions need
 153    sequence numbers concurrently.
 154
 155    Unexpected results might be obtained if a cache setting greater than
 156    one is used for a sequence object that will be used concurrently by
 157    multiple sessions. Each session will allocate and cache successive
 158    sequence values during one access to the sequence object and increase
 159    the sequence object's last_value accordingly. Then, the next cache-1
 160    uses of nextval within that session simply return the preallocated
 161    values without touching the sequence object. So, any numbers allocated
 162    but not used within a session will be lost when that session ends,
 163    resulting in “holes” in the sequence.
 164
 165    Furthermore, although multiple sessions are guaranteed to allocate
 166    distinct sequence values, the values might be generated out of sequence
 167    when all the sessions are considered. For example, with a cache setting
 168    of 10, session A might reserve values 1..10 and return nextval=1, then
 169    session B might reserve values 11..20 and return nextval=11 before
 170    session A has generated nextval=2. Thus, with a cache setting of one it
 171    is safe to assume that nextval values are generated sequentially; with
 172    a cache setting greater than one you should only assume that the
 173    nextval values are all distinct, not that they are generated purely
 174    sequentially. Also, last_value will reflect the latest value reserved
 175    by any session, whether or not it has yet been returned by nextval.
 176
 177    Another consideration is that a setval executed on such a sequence will
 178    not be noticed by other sessions until they have used up any
 179    preallocated values they have cached.
 180
 181 Examples
 182
 183    Create an ascending sequence called serial, starting at 101:
 184 CREATE SEQUENCE serial START 101;
 185
 186    Select the next number from this sequence:
 187 SELECT nextval('serial');
 188
 189  nextval
 190 ---------
 191      101
 192
 193    Select the next number from this sequence:
 194 SELECT nextval('serial');
 195
 196  nextval
 197 ---------
 198      102
 199
 200    Use this sequence in an INSERT command:
 201 INSERT INTO distributors VALUES (nextval('serial'), 'nothing');
 202
 203    Update the sequence value after a COPY FROM:
 204 BEGIN;
 205 COPY distributors FROM 'input_file';
 206 SELECT setval('serial', max(id)) FROM distributors;
 207 END;
 208
 209 Compatibility
 210
 211    CREATE SEQUENCE conforms to the SQL standard, with the following
 212    exceptions:
 213      * Obtaining the next value is done using the nextval() function
 214        instead of the standard's NEXT VALUE FOR expression.
 215      * The OWNED BY clause is a PostgreSQL extension.
 216
 217 See Also
 218
 219    ALTER SEQUENCE, DROP SEQUENCE