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

   1
   2 ALTER SEQUENCE
   3
   4    ALTER SEQUENCE — change the definition of a sequence generator
   5
   6 Synopsis
   7
   8 ALTER SEQUENCE [ IF 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     [ RESTART [ [ WITH ] restart ] ]
  15     [ CACHE cache ]
  16     [ OWNED BY { table_name.column_name | NONE } ]
  17 ALTER SEQUENCE [ IF EXISTS ] name SET { LOGGED | UNLOGGED }
  18 ALTER SEQUENCE [ IF EXISTS ] name OWNER TO { new_owner | CURRENT_ROLE | CURRENT_
  19 USER | SESSION_USER }
  20 ALTER SEQUENCE [ IF EXISTS ] name RENAME TO new_name
  21 ALTER SEQUENCE [ IF EXISTS ] name SET SCHEMA new_schema
  22
  23 Description
  24
  25    ALTER SEQUENCE changes the parameters of an existing sequence
  26    generator. Any parameters not specifically set in the ALTER SEQUENCE
  27    command retain their prior settings.
  28
  29    You must own the sequence to use ALTER SEQUENCE. To change a sequence's
  30    schema, you must also have CREATE privilege on the new schema. To alter
  31    the owner, you must be able to SET ROLE to the new owning role, and
  32    that role must have CREATE privilege on the sequence's schema. (These
  33    restrictions enforce that altering the owner doesn't do anything you
  34    couldn't do by dropping and recreating the sequence. However, a
  35    superuser can alter ownership of any sequence anyway.)
  36
  37 Parameters
  38
  39    name
  40           The name (optionally schema-qualified) of a sequence to be
  41           altered.
  42
  43    IF EXISTS
  44           Do not throw an error if the sequence does not exist. A notice
  45           is issued in this case.
  46
  47    data_type
  48           The optional clause AS data_type changes the data type of the
  49           sequence. Valid types are smallint, integer, and bigint.
  50
  51           Changing the data type automatically changes the minimum and
  52           maximum values of the sequence if and only if the previous
  53           minimum and maximum values were the minimum or maximum value of
  54           the old data type (in other words, if the sequence had been
  55           created using NO MINVALUE or NO MAXVALUE, implicitly or
  56           explicitly). Otherwise, the minimum and maximum values are
  57           preserved, unless new values are given as part of the same
  58           command. If the minimum and maximum values do not fit into the
  59           new data type, an error will be generated.
  60
  61    increment
  62           The clause INCREMENT BY increment is optional. A positive value
  63           will make an ascending sequence, a negative one a descending
  64           sequence. If unspecified, the old increment value will be
  65           maintained.
  66
  67    minvalue
  68           NO MINVALUE
  69           The optional clause MINVALUE minvalue determines the minimum
  70           value a sequence can generate. If NO MINVALUE is specified, the
  71           defaults of 1 and the minimum value of the data type for
  72           ascending and descending sequences, respectively, will be used.
  73           If neither option is specified, the current minimum value will
  74           be maintained.
  75
  76    maxvalue
  77           NO MAXVALUE
  78           The optional clause MAXVALUE maxvalue determines the maximum
  79           value for the sequence. If NO MAXVALUE is specified, the
  80           defaults of the maximum value of the data type and -1 for
  81           ascending and descending sequences, respectively, will be used.
  82           If neither option is specified, the current maximum value will
  83           be maintained.
  84
  85    CYCLE
  86           The optional CYCLE key word can be used to enable the sequence
  87           to wrap around when the maxvalue or minvalue has been reached by
  88           an ascending or descending sequence respectively. If the limit
  89           is reached, the next number generated will be the minvalue or
  90           maxvalue, respectively.
  91
  92    NO CYCLE
  93           If the optional NO CYCLE key word is specified, any calls to
  94           nextval after the sequence has reached its maximum value will
  95           return an error. If neither CYCLE or NO CYCLE are specified, the
  96           old cycle behavior will be maintained.
  97
  98    start
  99           The optional clause START WITH start changes the recorded start
 100           value of the sequence. This has no effect on the current
 101           sequence value; it simply sets the value that future ALTER
 102           SEQUENCE RESTART commands will use.
 103
 104    restart
 105           The optional clause RESTART [ WITH restart ] changes the current
 106           value of the sequence. This is similar to calling the setval
 107           function with is_called = false: the specified value will be
 108           returned by the next call of nextval. Writing RESTART with no
 109           restart value is equivalent to supplying the start value that
 110           was recorded by CREATE SEQUENCE or last set by ALTER SEQUENCE
 111           START WITH.
 112
 113           In contrast to a setval call, a RESTART operation on a sequence
 114           is transactional and blocks concurrent transactions from
 115           obtaining numbers from the same sequence. If that's not the
 116           desired mode of operation, setval should be used.
 117
 118    cache
 119           The clause CACHE cache enables sequence numbers to be
 120           preallocated and stored in memory for faster access. The minimum
 121           value is 1 (only one value can be generated at a time, i.e., no
 122           cache). If unspecified, the old cache value will be maintained.
 123
 124    SET { LOGGED | UNLOGGED }
 125           This form changes the sequence from unlogged to logged or
 126           vice-versa (see CREATE SEQUENCE). It cannot be applied to a
 127           temporary sequence.
 128
 129    OWNED BY table_name.column_name
 130           OWNED BY NONE
 131           The OWNED BY option causes the sequence to be associated with a
 132           specific table column, such that if that column (or its whole
 133           table) is dropped, the sequence will be automatically dropped as
 134           well. If specified, this association replaces any previously
 135           specified association for the sequence. The specified table must
 136           have the same owner and be in the same schema as the sequence.
 137           Specifying OWNED BY NONE removes any existing association,
 138           making the sequence “free-standing”.
 139
 140    new_owner
 141           The user name of the new owner of the sequence.
 142
 143    new_name
 144           The new name for the sequence.
 145
 146    new_schema
 147           The new schema for the sequence.
 148
 149 Notes
 150
 151    ALTER SEQUENCE will not immediately affect nextval results in backends,
 152    other than the current one, that have preallocated (cached) sequence
 153    values. They will use up all cached values prior to noticing the
 154    changed sequence generation parameters. The current backend will be
 155    affected immediately.
 156
 157    ALTER SEQUENCE does not affect the currval status for the sequence.
 158    (Before PostgreSQL 8.3, it sometimes did.)
 159
 160    ALTER SEQUENCE blocks concurrent nextval, currval, lastval, and setval
 161    calls.
 162
 163    For historical reasons, ALTER TABLE can be used with sequences too; but
 164    the only variants of ALTER TABLE that are allowed with sequences are
 165    equivalent to the forms shown above.
 166
 167 Examples
 168
 169    Restart a sequence called serial, at 105:
 170 ALTER SEQUENCE serial RESTART WITH 105;
 171
 172 Compatibility
 173
 174    ALTER SEQUENCE conforms to the SQL standard, except for the AS, START
 175    WITH, OWNED BY, OWNER TO, RENAME TO, and SET SCHEMA clauses, which are
 176    PostgreSQL extensions.
 177
 178 See Also
 179
 180    CREATE SEQUENCE, DROP SEQUENCE