Sequence caching and misc updates to SERIAL and CREATE/ALTER SEQUENCE pages #10219

ericharmeling · 2021-03-31T20:23:15Z

Fixes #7741.
Fixes #10094.
Fixes #10093.
Coupled with cockroachdb/cockroach#62877.

This PR includes:

New SQL diagrams for CREATE SEQUENCE and ALTER SEQUENCE.
Updated examples and output for CREATE SEQUENCE and ALTER SEQUENCE pages.
Docs for sequence caching statement parameters and serial sequence caching session variables/cluster settings.

I intentionally did not include an example for sequence caching, as I am not sure how/that we expose cached values, through system catalogs or otherwise...

To this point, CACHE does not appear in the SHOW CREATE output:

> CREATE SEQUENCE cache_test CACHE 10;
> SHOW CREATE SEQUENCE cache_test;

  table_name |                                       create_statement
-------------+------------------------------------------------------------------------------------------------
  cache_test | CREATE SEQUENCE public.cache_test MINVALUE 1 MAXVALUE 9223372036854775807 INCREMENT 1 START 1
(1 row)

cockroach-teamcity · 2021-03-31T20:23:20Z

This change is

cockroach-teamcity · 2021-03-31T20:28:51Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/46d44fc89c98882e7cef5cfa7b7ec562617f7f9a/

Edited pages:

cockroach-teamcity · 2021-03-31T20:37:01Z

Online preview: http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/68aa2048f4d94649345a4cf2ffe0d01dcc7694c4/

Edited pages:

ericharmeling · 2021-04-01T14:50:48Z

@ajwerner
Adding you for review here, as you were the primary reviewer on cockroachdb/cockroach#56954.

ajwerner · 2021-04-01T15:42:22Z

Big yikes on not showing the cache value. Nice job finding that.

ericharmeling · 2021-04-12T14:31:17Z

@ajwerner Ping on review

ajwerner

I'll backport the below PR into 21.1.1

cockroachdb/cockroach#63548

Reviewable status: complete! 1 of 0 LGTMs obtained

ianjevans

Looks good, just some small nits and added links.

ianjevans · 2021-04-21T02:26:06Z

v20.1/serial.md


-In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative feature, introduced in v2.0, is the [`SEQUENCE`](create-sequence.html).
+In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative feature is the [`SEQUENCE`](create-sequence.html).


Suggested change

In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative feature is the [`SEQUENCE`](create-sequence.html).

In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative is to use [`SEQUENCE`](create-sequence.html).

ianjevans · 2021-04-21T02:29:48Z

v20.2/create-sequence.md


-In this example, we create a sequence that starts at -1 and descends in increments of 2.
+In this example, we [create a table](create-table.html), using the `nextval()` function for a [default value](default-value.html), with the `customer_seq` sequence as its input:


Suggested change

In this example, we [create a table](create-table.html), using the `nextval()` function for a [default value](default-value.html), with the `customer_seq` sequence as its input:

In this example, we [create a table](create-table.html), using the [`nextval()` function](functions-and-operators.html#sequence-functions) for a [default value](default-value.html), with the `customer_seq` sequence as its input:

ianjevans · 2021-04-21T02:30:50Z

v20.2/create-sequence.md

+
+### Set the next value of a sequence
+
+In this example, we're going to change the next value of `customer_seq` using the `setval()` function. Currently, the next value will be `3` (i.e., `2` + `INCREMENT 1`). We will change the next value to `5`.


Suggested change

In this example, we're going to change the next value of `customer_seq` using the `setval()` function. Currently, the next value will be `3` (i.e., `2` + `INCREMENT 1`). We will change the next value to `5`.

In this example, we're going to change the next value of `customer_seq` using the [`setval()` function](functions-and-operators.html#sequence-functions). Currently, the next value will be `3` (i.e., `2` + `INCREMENT 1`). We will change the next value to `5`.

ianjevans · 2021-04-21T02:34:14Z

v20.2/serial.md


-In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative feature, introduced in v2.0, is the [`SEQUENCE`](create-sequence.html).
+In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative feature is the [`SEQUENCE`](create-sequence.html).


Suggested change

In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative feature is the [`SEQUENCE`](create-sequence.html).

In summary, the `SERIAL` type in PostgreSQL and CockroachDB, and the `AUTO_INCREMENT` type in MySQL, all behave the same in that they do not create strict sequences. CockroachDB will likely create more gaps than these other databases, but will generate these values much faster. An alternative is to use [`SEQUENCE`](create-sequence.html).

ianjevans · 2021-04-21T02:35:51Z

v21.1/create-sequence.md


-In this example, we create a sequence that starts at -1 and descends in increments of 2.
+In this example, we [create a table](create-table.html), using the `nextval()` function for a [default value](default-value.html), with the `customer_seq` sequence as its input:


Suggested change

In this example, we [create a table](create-table.html), using the `nextval()` function for a [default value](default-value.html), with the `customer_seq` sequence as its input:

In this example, we [create a table](create-table.html), using the [`nextval()` function](functions-and-operators.html#sequence-functions) for a [default value](default-value.html), with the `customer_seq` sequence as its input:

ianjevans · 2021-04-21T02:36:27Z

v21.1/create-sequence.md

+
+### Set the next value of a sequence
+
+In this example, we're going to change the next value of `customer_seq` using the `setval()` function. Currently, the next value will be `3` (i.e., `2` + `INCREMENT 1`). We will change the next value to `5`.


Suggested change

In this example, we're going to change the next value of `customer_seq` using the `setval()` function. Currently, the next value will be `3` (i.e., `2` + `INCREMENT 1`). We will change the next value to `5`.

In this example, we're going to change the next value of `customer_seq` using the [`setval()` function](functions-and-operators.html#sequence-functions). Currently, the next value will be `3` (i.e., `2` + `INCREMENT 1`). We will change the next value to `5`.

… pages

ericharmeling

TFTR @ianjevans !

Reviewable status: complete! 0 of 0 LGTMs obtained (and 1 stale) (waiting on @ianjevans)

v20.1/serial.md, line 238 at r1 (raw file):