begriffs open source - ai-pg/blob - full-docs/src/sgml/html/sql-createsequence.html

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