Sequence-Manipulation Functions

PostgreSQL 7.2 Documentation
Prev | Chapter 4. Functions and Operators | Next

# 4.11. Sequence-Manipulation Functions

Table 4-24. Sequence Functions

Function | Returns | Description
--- | --- | ---
`nextval`(`text`) | `bigint` | Advance sequence and return new value
`currval`(`text`) | `bigint` | Return value most recently obtained with `nextval`
`setval`(`text`,`bigint`) | `bigint` | Set sequence's current value
`setval`(`text`,`bigint`,`boolean`) | `bigint` | Set sequence's current value and `is_called` flag

This section describes PostgreSQL's functions for operating on sequence objects. Sequence objects (also called sequence generators or just sequences) are special single-row tables created with CREATE SEQUENCE. A sequence object is usually used to generate unique identifiers for rows of a table. The sequence functions provide simple, multiuser-safe methods for obtaining successive sequence values from sequence objects.

For largely historical reasons, the sequence to be operated on by a sequence-function call is specified by a text-string argument. To achieve some compatibility with the handling of ordinary SQL names, the sequence functions convert their argument to lower case unless the string is double-quoted. Thus

    nextval('foo')      operates on sequence foo
    nextval('FOO')      operates on sequence foo
    nextval('"Foo"')    operates on sequence Foo

Of course, the text argument can be the result of an expression, not only a simple literal, which is occasionally useful.

The available sequence functions are:

`nextval`

  Advance the sequence object to its next value and return that value. This is done atomically: even if multiple server processes execute `nextval` concurrently, each will safely receive a distinct sequence value.

`currval`

  Return the value most recently obtained by `nextval` for this sequence in the current server process. (An error is reported if `nextval` has never been called for this sequence in this process.) Notice that because this is returning a process-local value, it gives a predictable answer even if other server processes are executing `nextval` meanwhile.

`setval`

  Reset the sequence object's counter value. The two-parameter form sets the sequence's `last_value` field to the specified value and sets its `is_called` field to `true`, meaning that the next `nextval` will advance the sequence before returning a value. In the three-parameter form, `is_called` may be set either `true` or `false`. If it's set to `false`, the next `nextval` will return exactly the specified value, and sequence advancement commences with the following `nextval`. For example,

      SELECT setval('foo', 42);           Next nextval() will return 43
      SELECT setval('foo', 42, true);     Same as above
      SELECT setval('foo', 42, false);    Next nextval() will return 42

  The result returned by `setval` is just the value of its second argument.

> Important: To avoid blocking of concurrent transactions that obtain numbers from the same sequence, a `nextval` operation is never rolled back; that is, once a value has been fetched it is considered used, even if the transaction that did the `nextval` later aborts. This means that aborted transactions may leave unused "holes" in the sequence of assigned values. `setval` operations are never rolled back, either.

If a sequence object has been created with default parameters, `nextval()` calls on it will return successive values beginning with one. Other behaviors can be obtained by using special parameters in the CREATE SEQUENCE command; see its command reference page for more information.

Prev | Home | Next
Network Address Type Functions | Up | Conditional Expressions