Skip to content

Commit 1e05aa1

Browse files
mrotteveelmrotteveel
committed
#211 Review and improve ALTER SEQUENCE ... RESTART WITH documentation
+ misc sequence related copy-editing
1 parent 0ae7aef commit 1e05aa1

6 files changed

+139
-126
lines changed

‎src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-appx04-systables.adoc

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,7 @@ Information about external functions
6363
Attributes of the parameters of external functions
6464

6565
<<fblangref-appx04-generators>>::
66-
Information about generators (sequences)
66+
Information about sequences (generators)
6767

6868
<<fblangref-appx04-idxsegments>>::
6969
Segments and index positions
@@ -1245,7 +1245,7 @@ Used in conjunction with `RDB$RELATION_NAME` (see next).
12451245
[[fblangref-appx04-generators]]
12461246
== `RDB$GENERATORS`
12471247

1248-
`RDB$GENERATORS` stores generators (sequences) and keeps them up-to-date.
1248+
`RDB$GENERATORS` stores the metadata of sequences (generators).
12491249

12501250
[[fblangref40-appx04-tbl-generators]]
12511251
[cols="<4m,<3m,<5", frame="all", options="header",stripes="none"]
@@ -1256,39 +1256,41 @@ Used in conjunction with `RDB$RELATION_NAME` (see next).
12561256

12571257
|RDB$GENERATOR_NAME
12581258
|CHAR(63)
1259-
|The unique name of the generator
1259+
|The unique name of the sequence
12601260

12611261
|RDB$GENERATOR_ID
12621262
|SMALLINT
1263-
|The unique identifier assigned to the generator by the system
1263+
|The unique identifier assigned to the sequence by the system
12641264

12651265
|RDB$SYSTEM_FLAG
12661266
|SMALLINT
12671267
|Flag:
12681268

12691269
`0` - user-defined +
12701270
`1` or greater - system-defined
1271-
`6` - internal generator for identity column
1271+
`6` - internal sequence for identity column
12721272

12731273
|RDB$DESCRIPTION
12741274
|BLOB TEXT
1275-
|Could store comments related to the generator
1275+
|Optional description of the sequence (comment)
12761276

12771277
|RDB$SECURITY_CLASS
12781278
|CHAR(63)
1279-
|May reference a security class defined in the table `RDB$SECURITY_CLASSES`, in order to apply access control limits to all users of this generator
1279+
|May reference a security class defined in the table `RDB$SECURITY_CLASSES`, to apply access control limits to all users of this sequence
12801280

12811281
|RDB$OWNER_NAME
12821282
|CHAR(63)
1283-
|The username of the user who created the generator originally
1283+
|The username of the user who created the sequence originally
12841284

12851285
|RDB$INITIAL_VALUE
12861286
|BIGINT
1287-
|Stores the initial value (`START WITH` value) of the generator
1287+
|Stores the start value (`START WITH` value) of the sequence.
1288+
The start value is the first value generated by <<fblangref40-commons-nxtvlufor,`NEXT VALUE FOR`>> after a restart of the sequence.
12881289

12891290
|RDB$GENERATOR_INCREMENT
12901291
|INTEGER
1291-
|Stores the increment of the value (`INCREMENT BY` value) of the generator
1292+
|Stores the increment (`INCREMENT BY` value) of the sequence.
1293+
The increment is used by <<fblangref40-commons-nxtvlufor,`NEXT VALUE FOR`>>, but not by <<fblangref40-scalarfuncs-gen-id,`GEN_ID`>>.
12921294
|===
12931295

12941296
[[fblangref-appx04-indices]]

‎src/docs/asciidoc/en/refdocs/fblangref40/_fblangref40-dochist.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ The exact file history is recorded in our _git_ repository; see https://github.c
1414
|TBD
1515
|MR
1616
a|* Documented where to find time zone region names
17+
* Revise `SEQUENCE` DDL documentation regarding `START`/`RESTART` (https://github.com/FirebirdSQL/firebird-documentation/issues/211[#211])
1718
* Trigger order for the same position was documented as alphabetical by name;
1819
the actual order is undefined (https://github.com/FirebirdSQL/firebird-documentation/issues/213[#213])
1920

‎src/docs/asciidoc/en/refdocs/fblangref40/ddl/_fblangref40-ddl-sequence.adoc

Lines changed: 55 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ A sequence -- or generator -- is a database object used to get unique number va
55
"`Sequence`" is the SQL-compliant term for the same thing which -- in Firebird -- has traditionally been known as "`generator`".
66
Firebird has syntax for both terms.
77

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

1010
[CAUTION]
1111
====
@@ -42,41 +42,42 @@ CREATE {SEQUENCE | GENERATOR} _seq_name_
4242
^| Description
4343

4444
|seq_name
45-
|Sequence (generator) name.
45+
|Sequence name.
4646
The maximum length is 63 characters
4747

4848
|start_value
49-
|Initial value of the sequence.
50-
Default is 1.
49+
|First value produced by `NEXT VALUE FOR __seq_name__`.
50+
A 64-bit integer from -2^-63^ to 2^63^-1.
51+
Default is `1`.
5152

5253
|increment
53-
|Increment of the sequence (when using `NEXT VALUE FOR __seq_name__`);
54+
|Increment of the sequence when using `NEXT VALUE FOR __seq_name__`;
5455
cannot be `0`.
55-
Default is 1.
56+
Default is `1`.
5657
|===
5758

58-
The statements `CREATE SEQUENCE` and `CREATE GENERATOR` are synonymous -- both create a new sequence.
59-
Either can be used, but `CREATE SEQUENCE` is recommended as that is the syntax defined in the SQL standard.
60-
61-
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_.
59+
When a sequence is created, its current value is set so that the next value produced by `NEXT VALUE FOR __seq_name__` is equal to _start_value_.
6260
In other words, the current value of the sequence is set to (`__start_value__ - __increment__`).
63-
By default, the _start_value_ is 1 (one).
6461

65-
The optional `INCREMENT [BY]` clause allows you to specify an increment for the <<fblangref40-commons-nxtvlufor,`NEXT VALUE FOR _seq_name_`>> expression.
66-
By default, the increment is 1 (one).
67-
The increment cannot be set to 0 (zero).
68-
The `GEN_ID(seq_name, <step>)` function can be called instead, to "`step`" the series by a different integer number.
69-
The increment specified through `INCREMENT [BY]` is not used for `GEN_ID`.
62+
The optional `INCREMENT [BY]` clause allows you to specify a non-zero increment for the <<fblangref40-commons-nxtvlufor,`NEXT VALUE FOR __seq_name__`>> expression.
63+
64+
The <<fblangref40-scalarfuncs-gen-id,`GEN_ID(seq_name, __step__)`>> function can be called instead, to "`step`" the sequence by a different increment.
65+
The increment specified through `INCREMENT [BY]` is not used by `GEN_ID`.
66+
Using both `NEXT VALUE FOR` and `GEN_ID`, especially when the sequence has an increment other than `1`, may result in values you did not expect.
67+
For example, if you execute `CREATE SEQUENCE x START WITH 10 INCREMENT BY 10`, and then use `GEN_ID(x, 1)`, the value returned is `1`, and if you then call `NEXT VALUE FOR x`, you get `11`.
7068

7169
.Non-standard behaviour for negative increments
7270
[NOTE]
7371
====
7472
The SQL standard specifies that sequences with a negative increment should start at the maximum value of the sequence (2^63^ - 1) and count down.
75-
Firebird does not do that, and instead starts at `1`.
73+
Firebird does not do that, and instead starts at `1` unless you specify a `START WITH` value.
7674
7775
This may change in a future Firebird version.
7876
====
7977

78+
The statements `CREATE SEQUENCE` and `CREATE GENERATOR` are synonymous -- both create a new sequence.
79+
Either can be used, but `CREATE SEQUENCE` is recommended as that is the syntax defined in the SQL standard.
80+
8081
[[fblangref40-ddl-sequence-create-who]]
8182
=== Who Can Create a Sequence?
8283

@@ -85,7 +86,7 @@ The `CREATE SEQUENCE` (`CREATE GENERATOR`) statement can be executed by:
8586
* <<fblangref40-security-administrators,Administrators>>
8687
* Users with the `CREATE SEQUENCE` (`CREATE GENERATOR`) privilege
8788

88-
The user executing the `CREATE SEQUENCE` (`CREATE GENERATOR`) statement becomes its owner.
89+
The user executing `CREATE SEQUENCE` (`CREATE GENERATOR`) becomes its owner.
8990

9091
[[fblangref40-ddl-sequence-create-example]]
9192
=== Examples of `CREATE SEQUENCE`
@@ -137,7 +138,7 @@ DSQL
137138
[listing,subs=+quotes]
138139
----
139140
ALTER {SEQUENCE | GENERATOR} _seq_name_
140-
[RESTART [WITH _newvalue_]]
141+
[RESTART [WITH _start_value_]]
141142
[INCREMENT [BY] _increment_]
142143
----
143144

@@ -149,49 +150,46 @@ ALTER {SEQUENCE | GENERATOR} _seq_name_
149150
^| Description
150151

151152
|seq_name
152-
|Sequence (generator) name
153+
|Sequence name
153154

154-
|newvalue
155-
|New sequence (generator) value.
155+
|start_value
156+
|Next value produced by `NEXT VALUE FOR __seq_name__`.
156157
A 64-bit integer from -2^-63^ to 2^63^-1.
158+
Default is the start value in the metadata.
157159

158160
|increment
159161
|Increment of the sequence (when using `NEXT VALUE FOR __seq_name__`);
160162
cannot be `0`.
161163
|===
162164

163-
The `ALTER SEQUENCE` statement sets the current value of a sequence to the specified value
164-
and/or changes the increment of the sequence.
165+
The `ALTER SEQUENCE` statement sets the next value of the sequence, and/or changes the increment of the sequence.
165166

166-
The `RESTART WITH __newvalue__` clause allows you to set the next value generated by `NEXT VALUE FOR __seq_name__`.
167-
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.
168-
The `RESTART` clause (without `WITH`) restarts the sequence with the initial value stored in the metadata of the sequence.
167+
The `RESTART WITH __start_value__` clause sets the current value of the sequence so that the next value obtained from <<fblangref40-commons-nxtvlufor,`NEXT VALUE FOR __seq_name__`>> is equal to _start_value_.
168+
To achieve this, the current value of the sequence is set to (`__start_value__ - __increment__`) with _increment_ either as specified in the statement, or from the metadata of the sequence.
169+
The `RESTART` clause without `WITH __start_value__` behaves as if `WITH __start_value__` is specified with the start value from the metadata of the sequence.
169170

170171
[NOTE]
171172
====
172-
Contrary to Firebird 3.0, in 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.
173-
A subsequent `ALTER SEQUENCE RESTART` will use the initial value specified when the sequence was created, and not the _newvalue_ of this statement.
173+
Contrary to Firebird 3.0, since Firebird 4.0 `RESTART WITH __start_value__` only restarts the sequence with the specified value, and does not store _start_value_ as the new start value of the sequence.
174+
A subsequent `ALTER SEQUENCE RESTART` will use the start value specified when the sequence was created, and not the _start_value_ of this statement.
174175
This behaviour is specified in the SQL standard.
175176
176-
It is currently not possible to change the initial value stored in the metadata.
177+
It is currently not possible to change the start value stored in the metadata.
177178
====
178179

179180
[WARNING]
180181
====
181-
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.
182+
Incorrect use of `ALTER SEQUENCE` -- 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.
182183
====
183184

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

186-
[NOTE]
187-
====
188187
Changing the increment value takes effect for all queries that run after the transaction commits.
189188
Procedures that are called for the first time after changing the commit, will use the new value if they use `NEXT VALUE FOR`.
190-
Procedures that were already used (and cached in the metadata cache) will continue to use the old increment.
189+
Procedures that were already cached in the metadata cache will continue to use the old increment.
191190
You may need to close all connections to the database for the metadata cache to clear, and the new increment to be used.
192191
Procedures using `NEXT VALUE FOR` do not need to be recompiled to see the new increment.
193192
Procedures using `GEN_ID(gen, expression)` are not affected when the increment is changed.
194-
====
195193

196194
[[fblangref40-ddl-sequence-alter-who]]
197195
=== Who Can Alter a Sequence?
@@ -211,7 +209,7 @@ The `ALTER SEQUENCE` (`ALTER GENERATOR`) statement can be executed by:
211209
----
212210
ALTER SEQUENCE EMP_NO_GEN RESTART WITH 145;
213211
----
214-
. Resetting the base value of the sequence `EMP_NO_GEN` to the initial value stored in the metadata
212+
. Resetting the sequence `EMP_NO_GEN` to the start value stored in the metadata
215213
+
216214
[source]
217215
----
@@ -252,23 +250,24 @@ CREATE OR ALTER {SEQUENCE | GENERATOR} _seq_name_
252250
^| Description
253251

254252
|seq_name
255-
|Sequence (generator) name.
253+
|Sequence name.
256254
The maximum length is 63 characters
257255

258256
|start_value
259-
|Initial value of the sequence.
260-
Default is 1.
257+
|First or next value produced by `NEXT VALUE FOR __seq_name__`.
258+
A 64-bit integer from -2^-63^ to 2^63^-1.
259+
Default is `1`.
261260

262261
|increment
263-
|Increment of the sequence (when using `NEXT VALUE FOR __seq_name__`);
262+
|Increment of the sequence when using `NEXT VALUE FOR __seq_name__`;
264263
cannot be `0`.
265-
Default is 1.
264+
Default is `1`.
266265
|===
267266

268-
If the sequence does not exist, it will be created.
267+
If the sequence does not exist, it will be created as documented under <<fblangref40-ddl-sequence-create>>.
269268
An existing sequence will be changed:
270269

271-
- If `RESTART` is specified, the sequence will restarted with the initial value stored in the metadata
270+
- If `RESTART` is specified, the sequence is restarted with the start value stored in the metadata
272271
- If the `START WITH` clause is specified, the sequence is restarted with _start_value_, but the _start_value_ is not stored.
273272
In other words, it behaves as `RESTART WITH` in <<fblangref40-ddl-sequence-alter>>.
274273
- 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`
@@ -310,14 +309,14 @@ DROP {SEQUENCE | GENERATOR} _seq_name_
310309
^| Description
311310

312311
|seq_name
313-
|Sequence (generator) name.
312+
|Sequence name.
314313
The maximum length is 63 characters
315314
|===
316315

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

320-
The statements will fail if the sequence (generator) has dependencies.
319+
The statements will fail if the sequence has dependencies.
321320

322321
[[fblangref40-ddl-tbl-dropseq-who]]
323322
=== Who Can Drop a Sequence?
@@ -344,7 +343,7 @@ DROP SEQUENCE EMP_NO_GEN;
344343
== `RECREATE SEQUENCE`
345344

346345
.Used for
347-
Creating or recreating a sequence (generator)
346+
Creating or recreating a sequence
348347

349348
.Available in
350349
DSQL, ESQL
@@ -365,15 +364,18 @@ RECREATE {SEQUENCE | GENERATOR} _seq_name_
365364
^| Description
366365

367366
|seq_name
368-
|Sequence (generator) name.
367+
|Sequence name.
369368
The maximum length is 63 characters
370369

371370
|start_value
372-
|Initial value of the sequence
371+
|First value produced by `NEXT VALUE FOR __seq_name__`.
372+
A 64-bit integer from -2^-63^ to 2^63^-1.
373+
Default is `1`.
373374

374375
|increment
375376
|Increment of the sequence (when using `NEXT VALUE FOR __seq_name__`);
376-
cannot be `0`
377+
cannot be `0`.
378+
Default is `1`.
377379
|===
378380

379381
See <<fblangref40-ddl-sequence-create>> for the full syntax of `CREATE SEQUENCE` and descriptions of defining a sequences and its options.
@@ -419,10 +421,10 @@ SET GENERATOR _seq_name_ TO _new_val_
419421
^| Description
420422

421423
|seq_name
422-
|Generator (sequence) name
424+
|Sequence name
423425

424426
|new_val
425-
|New sequence (generator) value.
427+
|New sequence value.
426428
A 64-bit integer from -2^-63^ to 2^63^-1.
427429
|===
428430

@@ -440,7 +442,7 @@ Use of the standards-compliant `ALTER SEQUENCE` is recommended.
440442
The `SET GENERATOR` statement can be executed by:
441443

442444
* <<fblangref40-security-administrators,Administrators>>
443-
* The owner of the sequence (generator)
445+
* The owner of the sequence
444446
* Users with the `ALTER ANY SEQUENCE` (`ALTER ANY GENERATOR`) privilege
445447

446448
[[fblangref40-ddl-sequence-setgen-example]]

‎src/docs/asciidoc/en/refdocs/fblangref50/_fblangref50-appx04-systables.adoc

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1256,39 +1256,41 @@ Used in conjunction with `RDB$RELATION_NAME` (see next).
12561256

12571257
|RDB$GENERATOR_NAME
12581258
|CHAR(63)
1259-
|The unique name of the generator
1259+
|The unique name of the sequence
12601260

12611261
|RDB$GENERATOR_ID
12621262
|SMALLINT
1263-
|The unique identifier assigned to the generator by the system
1263+
|The unique identifier assigned to the sequence by the system
12641264

12651265
|RDB$SYSTEM_FLAG
12661266
|SMALLINT
12671267
|Flag:
12681268

12691269
`0` - user-defined +
12701270
`1` or greater - system-defined
1271-
`6` - internal generator for identity column
1271+
`6` - internal sequence for identity column
12721272

12731273
|RDB$DESCRIPTION
12741274
|BLOB TEXT
1275-
|Could store comments related to the generator
1275+
|Optional description of the sequence (comment)
12761276

12771277
|RDB$SECURITY_CLASS
12781278
|CHAR(63)
1279-
|May reference a security class defined in the table `RDB$SECURITY_CLASSES`, to apply access control limits to all users of this generator
1279+
|May reference a security class defined in the table `RDB$SECURITY_CLASSES`, to apply access control limits to all users of this sequence
12801280

12811281
|RDB$OWNER_NAME
12821282
|CHAR(63)
1283-
|The username of the user who created the generator originally
1283+
|The username of the user who created the sequence originally
12841284

12851285
|RDB$INITIAL_VALUE
12861286
|BIGINT
1287-
|Stores the initial value (`START WITH` value) of the generator
1287+
|Stores the start value (`START WITH` value) of the sequence.
1288+
The start value is the first value generated by <<fblangref50-commons-nxtvlufor,`NEXT VALUE FOR`>> after a restart of the sequence.
12881289

12891290
|RDB$GENERATOR_INCREMENT
12901291
|INTEGER
1291-
|Stores the increment of the value (`INCREMENT BY` value) of the generator
1292+
|Stores the increment (`INCREMENT BY` value) of the sequence.
1293+
The increment is used by <<fblangref50-commons-nxtvlufor,`NEXT VALUE FOR`>>, but not by <<fblangref50-scalarfuncs-gen-id,`GEN_ID`>>.
12921294
|===
12931295

12941296
[[fblangref-appx04-idxsegments]]

‎src/docs/asciidoc/en/refdocs/fblangref50/_fblangref50-dochist.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ The exact file history is recorded in our _git_ repository; see https://github.c
1515
|MR
1616
a|* Transformed a lot of NOTE-admonitions to be simple paragraphs or lists, or removed them entirely
1717
* Documented where to find time zone region names
18+
* Revise `SEQUENCE` DDL documentation regarding `START`/`RESTART` (https://github.com/FirebirdSQL/firebird-documentation/issues/211[#211])
1819
* Trigger order for the same position was documented as alphabetical by name;
1920
the actual order is undefined (https://github.com/FirebirdSQL/firebird-documentation/issues/213[#213])
2021

0 commit comments

Comments
 (0)