RECREATE SEQUENCE

A sequence — or generator — is a database object used to get unique number values to fill a series. “Sequence” is the SQL-compliant term for the same thing which — in Firebird — has traditionally been known as “generator”. Firebird has syntax for both terms.

Sequences are always stored as 64-bit integers, regardless of the SQL dialect of the database.

Caution

If a client is connected using Dialect 1, the server handles sequence values as 32-bit integers. Passing a sequence value to a 32-bit field or variable will not cause errors as long as the current value of the sequence does not exceed the limits of a 32-bit number. However, as soon as the sequence value exceeds this limit, a database in Dialect 3 will produce an error. A database in Dialect 1 will truncate (overflow) the value, which could compromise the uniqueness of the series.

This section describes how to create, alter, set and drop sequences.

`CREATE SEQUENCE`

Creates a SEQUENCE (GENERATOR)

Available in

DSQL, ESQL

Syntax

CREATE {SEQUENCE | GENERATOR} seq_name
  [START WITH start_value]
  [INCREMENT [BY] increment]

Table 1. `CREATE SEQUENCE` Statement Parameters
Parameter	Description
seq_name	Sequence (generator) name. The maximum length is 63 characters
start_value	Initial value of the sequence. Default is 1.
increment	Increment of the sequence (when using `NEXT VALUE FOR seq_name`); cannot be `0`. Default is 1.

The statements CREATE SEQUENCE and CREATE GENERATOR are synonymous — both create a new sequence. Either can be used, but CREATE SEQUENCE is recommended as that is the syntax defined in the SQL standard.

When a sequence is created, its current value is set so that the next value obtained from NEXT VALUE FOR seq_name is equal to start_value. In other words, the current value of the sequence is set to (start_value - increment). By default, the start_value is 1 (one).

The optional INCREMENT [BY] clause allows you to specify an increment for the NEXT VALUE FOR seq_name expression. By default, the increment is 1 (one). The increment cannot be set to 0 (zero). The GEN_ID(seq_name, <step>) function can be called instead, to “step” the series by a different integer number. The increment specified through INCREMENT [BY] is not used for GEN_ID.

Note	Non-standard behaviour for negative increments The SQL standard specifies that sequences with a negative increment should start at the maximum value of the sequence (2⁶³ - 1) and count down. Firebird does not do that, and instead starts at `1`. This may change in a future Firebird version.

Who Can Create a Sequence?

The CREATE SEQUENCE (CREATE GENERATOR) statement can be executed by:

Administrators
Users with the CREATE SEQUENCE (CREATE GENERATOR) privilege

The user executing the CREATE SEQUENCE (CREATE GENERATOR) statement becomes its owner.

Examples of `CREATE SEQUENCE`

Creating the EMP_NO_GEN sequence using CREATE SEQUENCE.
```
CREATE SEQUENCE EMP_NO_GEN;
```
Creating the EMP_NO_GEN sequence using CREATE GENERATOR.
```
CREATE GENERATOR EMP_NO_GEN;
```
Creating the EMP_NO_GEN sequence with an initial value of 5 and an increment of 1.
```
CREATE SEQUENCE EMP_NO_GEN START WITH 5;
```
Creating the EMP_NO_GEN sequence with an initial value of 1 and an increment of 10.
```
CREATE SEQUENCE EMP_NO_GEN INCREMENT BY 10;
```
Creating the EMP_NO_GEN sequence with an initial value of 5 and an increment of 10.
```
CREATE SEQUENCE EMP_NO_GEN START WITH 5 INCREMENT BY 10;
```

`ALTER SEQUENCE`

Sets the next value of a sequence, or changes its increment

Available in

DSQL

Syntax

ALTER {SEQUENCE | GENERATOR} seq_name
  [RESTART [WITH newvalue]]
  [INCREMENT [BY] increment]

Table 1. `ALTER SEQUENCE` Statement Parameters
Parameter	Description
seq_name	Sequence (generator) name
newvalue	New sequence (generator) value. A 64-bit integer from -2^-63 to 2⁶³-1.
increment	Increment of the sequence (when using `NEXT VALUE FOR seq_name`); cannot be `0`.

The ALTER SEQUENCE statement sets the current value of a sequence to the specified value and/or changes the increment of the sequence.

The RESTART WITH newvalue clause allows you to set the next value generated by NEXT VALUE FOR seq_name. To achieve this, the current value of the sequence is set to (newvalue - increment) with increment either as specified in the statement, or stored in the metadata of the sequence. The RESTART clause (without WITH) restarts the sequence with the initial value stored in the metadata of the sequence.

Note

Contrary to Firebird 3.0, since Firebird 4.0 RESTART WITH newvalue only restarts the sequence with the specified value, and does not store newvalue as the new initial value of the sequence. A subsequent ALTER SEQUENCE RESTART will use the initial value specified when the sequence was created, and not the newvalue of this statement. This behaviour is specified in the SQL standard.

It is currently not possible to change the initial value stored in the metadata.

Warning

Incorrect use of the ALTER SEQUENCE statement (changing the current value of the sequence or generator) is likely to break the logical integrity of data, or result in primary key or unique constraint violations.

INCREMENT [BY] allows you to change the sequence increment for the NEXT VALUE FOR expression.

Note

Changing the increment value takes effect for all queries that run after the transaction commits. Procedures that are called for the first time after changing the commit, will use the new value if they use NEXT VALUE FOR. Procedures that were already used (and cached in the metadata cache) will continue to use the old increment. You may need to close all connections to the database for the metadata cache to clear, and the new increment to be used. Procedures using NEXT VALUE FOR do not need to be recompiled to see the new increment. Procedures using GEN_ID(gen, expression) are not affected when the increment is changed.

Who Can Alter a Sequence?

The ALTER SEQUENCE (ALTER GENERATOR) statement can be executed by:

Administrators
The owner of the sequence
Users with the ALTER ANY SEQUENCE (ALTER ANY GENERATOR) privilege

Examples of `ALTER SEQUENCE`

Setting the value of the EMP_NO_GEN sequence so the next value is 145.
```
ALTER SEQUENCE EMP_NO_GEN RESTART WITH 145;
```
Resetting the base value of the sequence EMP_NO_GEN to the initial value stored in the metadata
```
ALTER SEQUENCE EMP_NO_GEN RESTART;
```
Changing the increment of sequence EMP_NO_GEN to 10
```
ALTER SEQUENCE EMP_NO_GEN INCREMENT BY 10;
```

`CREATE OR ALTER SEQUENCE`

Creates a sequence if it doesn’t exist, or alters a sequence

Available in

DSQL, ESQL

Syntax

CREATE OR ALTER {SEQUENCE | GENERATOR} seq_name
  {RESTART | START WITH start_value}
  [INCREMENT [BY] increment]

Table 1. `CREATE OR ALTER SEQUENCE` Statement Parameters
Parameter	Description
seq_name	Sequence (generator) name. The maximum length is 63 characters
start_value	Initial value of the sequence. Default is 1.
increment	Increment of the sequence (when using `NEXT VALUE FOR seq_name`); cannot be `0`. Default is 1.

If the sequence does not exist, it will be created. An existing sequence will be changed:

If RESTART is specified, the sequence will restart with the initial value stored in the metadata
If the START WITH clause is specified, the sequence is restarted with start_value, but the start_value is not stored. In other words, it behaves as RESTART WITH in [fblangref50-ddl-sequence-alter].
If the INCREMENT [BY] clause is specified, increment is stored as the increment in the metadata, and used for subsequent calls to NEXT VALUE FOR

Example of `CREATE OR ALTER SEQUENCE`

Create a new or modify an existing sequence EMP_NO_GEN

CREATE OR ALTER SEQUENCE EMP_NO_GEN
  START WITH 10
  INCREMENT BY 1

`DROP SEQUENCE`

Drops a SEQUENCE (GENERATOR)

Available in

DSQL, ESQL

Syntax

DROP {SEQUENCE | GENERATOR} seq_name

Table 1. `DROP SEQUENCE` Statement Parameter
Parameter	Description
seq_name	Sequence (generator) name. The maximum length is 63 characters

The statements DROP SEQUENCE and DROP GENERATOR statements are equivalent: both drop (delete) an existing sequence (generator). Either is valid but DROP SEQUENCE, being defined in the SQL standard, is recommended.

The statements will fail if the sequence (generator) has dependencies.

Who Can Drop a Sequence?

The DROP SEQUENCE (DROP GENERATOR) statement can be executed by:

Administrators
The owner of the sequence
Users with the DROP ANY SEQUENCE (DROP ANY GENERATOR) privilege

Example of `DROP SEQUENCE`

Dropping the EMP_NO_GEN series:

DROP SEQUENCE EMP_NO_GEN;

`RECREATE SEQUENCE`

Drops a sequence if it exists, and creates a sequence (generator)

Available in

DSQL, ESQL

Syntax

RECREATE {SEQUENCE | GENERATOR} seq_name
  [START WITH start_value]
  [INCREMENT [BY] increment]

Table 1. `RECREATE SEQUENCE` Statement Parameters
Parameter	Description
seq_name	Sequence (generator) name. The maximum length is 63 characters
start_value	Initial value of the sequence
increment	Increment of the sequence (when using `NEXT VALUE FOR seq_name`); cannot be `0`

See [fblangref50-ddl-sequence-create] for the full syntax of CREATE SEQUENCE and descriptions of defining a sequences and its options.

RECREATE SEQUENCE creates or recreates a sequence. If a sequence with this name already exists, the RECREATE SEQUENCE statement will try to drop it and create a new one. Existing dependencies will prevent the statement from executing.

Example of `RECREATE SEQUENCE`

Recreating sequence EMP_NO_GEN

RECREATE SEQUENCE EMP_NO_GEN
  START WITH 10
  INCREMENT BY 2;

`SET GENERATOR`

Sets the current value of a sequence (generator)

Available in

DSQL, ESQL

Syntax

SET GENERATOR seq_name TO new_val

Table 1. `SET GENERATOR` Statement Parameters
Parameter	Description
seq_name	Generator (sequence) name
new_val	New sequence (generator) value. A 64-bit integer from -2^-63 to 2⁶³-1.

The SET GENERATOR statement sets the current value of a sequence or generator to the specified value.

Note	Although `SET GENERATOR` is considered outdated, it is retained for backward compatibility. Use of the standards-compliant `ALTER SEQUENCE` is recommended.

Who Can Use a `SET GENERATOR`?

The SET GENERATOR statement can be executed by:

Administrators
The owner of the sequence (generator)
Users with the ALTER ANY SEQUENCE (ALTER ANY GENERATOR) privilege

Example of `SET GENERATOR`

Setting the value of the EMP_NO_GEN sequence to 145:

SET GENERATOR EMP_NO_GEN TO 145;

Note

Similar effects can be achieved with [fblangref50-ddl-sequence-alter]:

ALTER SEQUENCE EMP_NO_GEN
  RESTART WITH 145 + increment;

Here, the value of increment is the current increment of the sequence. We need add it as ALTER SEQUENCE calculates the current value to set based on the next value it should produce.

RECREATE SEQUENCE

SEQUENCE (GENERATOR)

CREATE SEQUENCE

Who Can Create a Sequence?

Examples of CREATE SEQUENCE

ALTER SEQUENCE

Who Can Alter a Sequence?

Examples of ALTER SEQUENCE

CREATE OR ALTER SEQUENCE

Example of CREATE OR ALTER SEQUENCE

DROP SEQUENCE

Who Can Drop a Sequence?

Example of DROP SEQUENCE

RECREATE SEQUENCE

Example of RECREATE SEQUENCE

SET GENERATOR

Who Can Use a SET GENERATOR?

Example of SET GENERATOR

`SEQUENCE` (`GENERATOR`)

`CREATE SEQUENCE`

Examples of `CREATE SEQUENCE`

`ALTER SEQUENCE`

Examples of `ALTER SEQUENCE`

`CREATE OR ALTER SEQUENCE`

Example of `CREATE OR ALTER SEQUENCE`

`DROP SEQUENCE`

Example of `DROP SEQUENCE`

`RECREATE SEQUENCE`

Example of `RECREATE SEQUENCE`

`SET GENERATOR`

Who Can Use a `SET GENERATOR`?

Example of `SET GENERATOR`