begriffs open source - ai-pg/blob - full-docs/man7/CREATE_SEQUENCE.7

   1 '\" t
   2 .\"     Title: CREATE SEQUENCE
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE SEQUENCE" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_SEQUENCE \- define a new sequence generator
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE [ { TEMPORARY | TEMP } | UNLOGGED ] SEQUENCE [ IF NOT EXISTS ] \fIname\fR
  36     [ AS \fIdata_type\fR ]
  37     [ INCREMENT [ BY ] \fIincrement\fR ]
  38     [ MINVALUE \fIminvalue\fR | NO MINVALUE ] [ MAXVALUE \fImaxvalue\fR | NO MAXVALUE ]
  39     [ [ NO ] CYCLE ]
  40     [ START [ WITH ] \fIstart\fR ]
  41     [ CACHE \fIcache\fR ]
  42     [ OWNED BY { \fItable_name\fR\&.\fIcolumn_name\fR | NONE } ]
  43 .fi
  44 .SH "DESCRIPTION"
  45 .PP
  46 \fBCREATE SEQUENCE\fR
  47 creates a new sequence number generator\&. This involves creating and initializing a new special single\-row table with the name
  48 \fIname\fR\&. The generator will be owned by the user issuing the command\&.
  49 .PP
  50 If a schema name is given then the sequence is created in the specified schema\&. Otherwise it is created in the current schema\&. Temporary sequences exist in a special schema, so a schema name cannot be given when creating a temporary sequence\&. The sequence name must be distinct from the name of any other relation (table, sequence, index, view, materialized view, or foreign table) in the same schema\&.
  51 .PP
  52 After a sequence is created, you use the functions
  53 \fBnextval\fR,
  54 \fBcurrval\fR, and
  55 \fBsetval\fR
  56 to operate on the sequence\&. These functions are documented in
  57 Section\ \&9.17\&.
  58 .PP
  59 Although you cannot update a sequence directly, you can use a query like:
  60 .sp
  61 .if n \{\
  62 .RS 4
  63 .\}
  64 .nf
  65 SELECT * FROM \fIname\fR;
  66 .fi
  67 .if n \{\
  68 .RE
  69 .\}
  70 .sp
  71 to examine the parameters and current state of a sequence\&. In particular, the
  72 last_value
  73 field of the sequence shows the last value allocated by any session\&. (Of course, this value might be obsolete by the time it\*(Aqs printed, if other sessions are actively doing
  74 \fBnextval\fR
  75 calls\&.)
  76 .SH "PARAMETERS"
  77 .PP
  78 TEMPORARY or TEMP
  79 .RS 4
  80 If specified, the sequence object is created only for this session, and is automatically dropped on session exit\&. Existing permanent sequences with the same name are not visible (in this session) while the temporary sequence exists, unless they are referenced with schema\-qualified names\&.
  81 .RE
  82 .PP
  83 UNLOGGED
  84 .RS 4
  85 If specified, the sequence is created as an unlogged sequence\&. Changes to unlogged sequences are not written to the write\-ahead log\&. They are not crash\-safe: an unlogged sequence is automatically reset to its initial state after a crash or unclean shutdown\&. Unlogged sequences are also not replicated to standby servers\&.
  86 .sp
  87 Unlike unlogged tables, unlogged sequences do not offer a significant performance advantage\&. This option is mainly intended for sequences associated with unlogged tables via identity columns or serial columns\&. In those cases, it usually wouldn\*(Aqt make sense to have the sequence WAL\-logged and replicated but not its associated table\&.
  88 .RE
  89 .PP
  90 IF NOT EXISTS
  91 .RS 4
  92 Do not throw an error if a relation with the same name already exists\&. A notice is issued in this case\&. Note that there is no guarantee that the existing relation is anything like the sequence that would have been created \(em it might not even be a sequence\&.
  93 .RE
  94 .PP
  95 \fIname\fR
  96 .RS 4
  97 The name (optionally schema\-qualified) of the sequence to be created\&.
  98 .RE
  99 .PP
 100 \fIdata_type\fR
 101 .RS 4
 102 The optional clause
 103 AS \fIdata_type\fR
 104 specifies the data type of the sequence\&. Valid types are
 105 smallint,
 106 integer, and
 107 bigint\&.
 108 bigint
 109 is the default\&. The data type determines the default minimum and maximum values of the sequence\&.
 110 .RE
 111 .PP
 112 \fIincrement\fR
 113 .RS 4
 114 The optional clause
 115 INCREMENT BY \fIincrement\fR
 116 specifies which value is added to the current sequence value to create a new value\&. A positive value will make an ascending sequence, a negative one a descending sequence\&. The default value is 1\&.
 117 .RE
 118 .PP
 119 \fIminvalue\fR
 120 .br
 121 NO MINVALUE
 122 .RS 4
 123 The optional clause
 124 MINVALUE \fIminvalue\fR
 125 determines the minimum value a sequence can generate\&. If this clause is not supplied or
 126 \fBNO MINVALUE\fR
 127 is specified, then defaults will be used\&. The default for an ascending sequence is 1\&. The default for a descending sequence is the minimum value of the data type\&.
 128 .RE
 129 .PP
 130 \fImaxvalue\fR
 131 .br
 132 NO MAXVALUE
 133 .RS 4
 134 The optional clause
 135 MAXVALUE \fImaxvalue\fR
 136 determines the maximum value for the sequence\&. If this clause is not supplied or
 137 \fBNO MAXVALUE\fR
 138 is specified, then default values will be used\&. The default for an ascending sequence is the maximum value of the data type\&. The default for a descending sequence is \-1\&.
 139 .RE
 140 .PP
 141 CYCLE
 142 .br
 143 NO CYCLE
 144 .RS 4
 145 The
 146 CYCLE
 147 option allows the sequence to wrap around when the
 148 \fImaxvalue\fR
 149 or
 150 \fIminvalue\fR
 151 has been reached by an ascending or descending sequence respectively\&. If the limit is reached, the next number generated will be the
 152 \fIminvalue\fR
 153 or
 154 \fImaxvalue\fR, respectively\&.
 155 .sp
 156 If
 157 NO CYCLE
 158 is specified, any calls to
 159 \fBnextval\fR
 160 after the sequence has reached its maximum value will return an error\&. If neither
 161 CYCLE
 162 or
 163 NO CYCLE
 164 are specified,
 165 NO CYCLE
 166 is the default\&.
 167 .RE
 168 .PP
 169 \fIstart\fR
 170 .RS 4
 171 The optional clause
 172 START WITH \fIstart\fR
 173 allows the sequence to begin anywhere\&. The default starting value is
 174 \fIminvalue\fR
 175 for ascending sequences and
 176 \fImaxvalue\fR
 177 for descending ones\&.
 178 .RE
 179 .PP
 180 \fIcache\fR
 181 .RS 4
 182 The optional clause
 183 CACHE \fIcache\fR
 184 specifies how many sequence numbers are to be preallocated and stored in memory for faster access\&. The minimum value is 1 (only one value can be generated at a time, i\&.e\&., no cache), and this is also the default\&.
 185 .RE
 186 .PP
 187 OWNED BY \fItable_name\fR\&.\fIcolumn_name\fR
 188 .br
 189 OWNED BY NONE
 190 .RS 4
 191 The
 192 OWNED BY
 193 option causes the sequence to be associated with a specific table column, such that if that column (or its whole table) is dropped, the sequence will be automatically dropped as well\&. The specified table must have the same owner and be in the same schema as the sequence\&.
 194 OWNED BY NONE, the default, specifies that there is no such association\&.
 195 .RE
 196 .SH "NOTES"
 197 .PP
 198 Use
 199 \fBDROP SEQUENCE\fR
 200 to remove a sequence\&.
 201 .PP
 202 Sequences are based on
 203 bigint
 204 arithmetic, so the range cannot exceed the range of an eight\-byte integer (\-9223372036854775808 to 9223372036854775807)\&.
 205 .PP
 206 Because
 207 \fBnextval\fR
 208 and
 209 \fBsetval\fR
 210 calls are never rolled back, sequence objects cannot be used if
 211 \(lqgapless\(rq
 212 assignment of sequence numbers is needed\&. It is possible to build gapless assignment by using exclusive locking of a table containing a counter; but this solution is much more expensive than sequence objects, especially if many transactions need sequence numbers concurrently\&.
 213 .PP
 214 Unexpected results might be obtained if a
 215 \fIcache\fR
 216 setting greater than one is used for a sequence object that will be used concurrently by multiple sessions\&. Each session will allocate and cache successive sequence values during one access to the sequence object and increase the sequence object\*(Aqs
 217 last_value
 218 accordingly\&. Then, the next
 219 \fIcache\fR\-1 uses of
 220 \fBnextval\fR
 221 within that session simply return the preallocated values without touching the sequence object\&. So, any numbers allocated but not used within a session will be lost when that session ends, resulting in
 222 \(lqholes\(rq
 223 in the sequence\&.
 224 .PP
 225 Furthermore, although multiple sessions are guaranteed to allocate distinct sequence values, the values might be generated out of sequence when all the sessions are considered\&. For example, with a
 226 \fIcache\fR
 227 setting of 10, session A might reserve values 1\&.\&.10 and return
 228 \fBnextval\fR=1, then session B might reserve values 11\&.\&.20 and return
 229 \fBnextval\fR=11 before session A has generated
 230 \fBnextval\fR=2\&. Thus, with a
 231 \fIcache\fR
 232 setting of one it is safe to assume that
 233 \fBnextval\fR
 234 values are generated sequentially; with a
 235 \fIcache\fR
 236 setting greater than one you should only assume that the
 237 \fBnextval\fR
 238 values are all distinct, not that they are generated purely sequentially\&. Also,
 239 last_value
 240 will reflect the latest value reserved by any session, whether or not it has yet been returned by
 241 \fBnextval\fR\&.
 242 .PP
 243 Another consideration is that a
 244 \fBsetval\fR
 245 executed on such a sequence will not be noticed by other sessions until they have used up any preallocated values they have cached\&.
 246 .SH "EXAMPLES"
 247 .PP
 248 Create an ascending sequence called
 249 serial, starting at 101:
 250 .sp
 251 .if n \{\
 252 .RS 4
 253 .\}
 254 .nf
 255 CREATE SEQUENCE serial START 101;
 256 .fi
 257 .if n \{\
 258 .RE
 259 .\}
 260 .PP
 261 Select the next number from this sequence:
 262 .sp
 263 .if n \{\
 264 .RS 4
 265 .\}
 266 .nf
 267 SELECT nextval(\*(Aqserial\*(Aq);
 268
 269  nextval
 270 \-\-\-\-\-\-\-\-\-
 271      101
 272 .fi
 273 .if n \{\
 274 .RE
 275 .\}
 276 .PP
 277 Select the next number from this sequence:
 278 .sp
 279 .if n \{\
 280 .RS 4
 281 .\}
 282 .nf
 283 SELECT nextval(\*(Aqserial\*(Aq);
 284
 285  nextval
 286 \-\-\-\-\-\-\-\-\-
 287      102
 288 .fi
 289 .if n \{\
 290 .RE
 291 .\}
 292 .PP
 293 Use this sequence in an
 294 \fBINSERT\fR
 295 command:
 296 .sp
 297 .if n \{\
 298 .RS 4
 299 .\}
 300 .nf
 301 INSERT INTO distributors VALUES (nextval(\*(Aqserial\*(Aq), \*(Aqnothing\*(Aq);
 302 .fi
 303 .if n \{\
 304 .RE
 305 .\}
 306 .PP
 307 Update the sequence value after a
 308 \fBCOPY FROM\fR:
 309 .sp
 310 .if n \{\
 311 .RS 4
 312 .\}
 313 .nf
 314 BEGIN;
 315 COPY distributors FROM \*(Aqinput_file\*(Aq;
 316 SELECT setval(\*(Aqserial\*(Aq, max(id)) FROM distributors;
 317 END;
 318 .fi
 319 .if n \{\
 320 .RE
 321 .\}
 322 .SH "COMPATIBILITY"
 323 .PP
 324 \fBCREATE SEQUENCE\fR
 325 conforms to the
 326 SQL
 327 standard, with the following exceptions:
 328 .sp
 329 .RS 4
 330 .ie n \{\
 331 \h'-04'\(bu\h'+03'\c
 332 .\}
 333 .el \{\
 334 .sp -1
 335 .IP \(bu 2.3
 336 .\}
 337 Obtaining the next value is done using the
 338 \fBnextval()\fR
 339 function instead of the standard\*(Aqs
 340 \fBNEXT VALUE FOR\fR
 341 expression\&.
 342 .RE
 343 .sp
 344 .RS 4
 345 .ie n \{\
 346 \h'-04'\(bu\h'+03'\c
 347 .\}
 348 .el \{\
 349 .sp -1
 350 .IP \(bu 2.3
 351 .\}
 352 The
 353 OWNED BY
 354 clause is a
 355 PostgreSQL
 356 extension\&.
 357 .RE
 358 .SH "SEE ALSO"
 359 ALTER SEQUENCE (\fBALTER_SEQUENCE\fR(7)), DROP SEQUENCE (\fBDROP_SEQUENCE\fR(7))