begriffs open source - ai-pg/blob - full-docs/txt/functions-sequence.txt

   1
   2 9.17. Sequence Manipulation Functions #
   3
   4    This section describes functions for operating on sequence objects,
   5    also called sequence generators or just sequences. Sequence objects are
   6    special single-row tables created with CREATE SEQUENCE. Sequence
   7    objects are commonly used to generate unique identifiers for rows of a
   8    table. The sequence functions, listed in Table 9.55, provide simple,
   9    multiuser-safe methods for obtaining successive sequence values from
  10    sequence objects.
  11
  12    Table 9.55. Sequence Functions
  13
  14    Function
  15
  16    Description
  17
  18    nextval ( regclass ) → bigint
  19
  20    Advances the sequence object to its next value and returns that value.
  21    This is done atomically: even if multiple sessions execute nextval
  22    concurrently, each will safely receive a distinct sequence value. If
  23    the sequence object has been created with default parameters,
  24    successive nextval calls will return successive values beginning with
  25    1. Other behaviors can be obtained by using appropriate parameters in
  26    the CREATE SEQUENCE command.
  27
  28    This function requires USAGE or UPDATE privilege on the sequence.
  29
  30    setval ( regclass, bigint [, boolean ] ) → bigint
  31
  32    Sets the sequence object's current value, and optionally its is_called
  33    flag. The two-parameter form sets the sequence's last_value field to
  34    the specified value and sets its is_called field to true, meaning that
  35    the next nextval will advance the sequence before returning a value.
  36    The value that will be reported by currval is also set to the specified
  37    value. In the three-parameter form, is_called can be set to either true
  38    or false. true has the same effect as the two-parameter form. If it is
  39    set to false, the next nextval will return exactly the specified value,
  40    and sequence advancement commences with the following nextval.
  41    Furthermore, the value reported by currval is not changed in this case.
  42    For example,
  43 SELECT setval('myseq', 42);           Next nextval will return 43
  44 SELECT setval('myseq', 42, true);     Same as above
  45 SELECT setval('myseq', 42, false);    Next nextval will return 42
  46
  47    The result returned by setval is just the value of its second argument.
  48
  49    This function requires UPDATE privilege on the sequence.
  50
  51    currval ( regclass ) → bigint
  52
  53    Returns the value most recently obtained by nextval for this sequence
  54    in the current session. (An error is reported if nextval has never been
  55    called for this sequence in this session.) Because this is returning a
  56    session-local value, it gives a predictable answer whether or not other
  57    sessions have executed nextval since the current session did.
  58
  59    This function requires USAGE or SELECT privilege on the sequence.
  60
  61    lastval () → bigint
  62
  63    Returns the value most recently returned by nextval in the current
  64    session. This function is identical to currval, except that instead of
  65    taking the sequence name as an argument it refers to whichever sequence
  66    nextval was most recently applied to in the current session. It is an
  67    error to call lastval if nextval has not yet been called in the current
  68    session.
  69
  70    This function requires USAGE or SELECT privilege on the last used
  71    sequence.
  72
  73 Caution
  74
  75    To avoid blocking concurrent transactions that obtain numbers from the
  76    same sequence, the value obtained by nextval is not reclaimed for
  77    re-use if the calling transaction later aborts. This means that
  78    transaction aborts or database crashes can result in gaps in the
  79    sequence of assigned values. That can happen without a transaction
  80    abort, too. For example an INSERT with an ON CONFLICT clause will
  81    compute the to-be-inserted tuple, including doing any required nextval
  82    calls, before detecting any conflict that would cause it to follow the
  83    ON CONFLICT rule instead. Thus, PostgreSQL sequence objects cannot be
  84    used to obtain “gapless” sequences.
  85
  86    Likewise, sequence state changes made by setval are immediately visible
  87    to other transactions, and are not undone if the calling transaction
  88    rolls back.
  89
  90    If the database cluster crashes before committing a transaction
  91    containing a nextval or setval call, the sequence state change might
  92    not have made its way to persistent storage, so that it is uncertain
  93    whether the sequence will have its original or updated state after the
  94    cluster restarts. This is harmless for usage of the sequence within the
  95    database, since other effects of uncommitted transactions will not be
  96    visible either. However, if you wish to use a sequence value for
  97    persistent outside-the-database purposes, make sure that the nextval
  98    call has been committed before doing so.
  99
 100    The sequence to be operated on by a sequence function is specified by a
 101    regclass argument, which is simply the OID of the sequence in the
 102    pg_class system catalog. You do not have to look up the OID by hand,
 103    however, since the regclass data type's input converter will do the
 104    work for you. See Section 8.19 for details.