Add docs on CREATE SEQUENCE PER NODE CACHE (#19747)

Fixes DOC-9830

NB. This change applied to all supported versions v24.1+

Author: rmloveland

src/current/_includes/v24.1/misc/session-vars.md

@@ -65,7 +65,7 @@
 | <a id="reorder-joins-limit"></a> `reorder_joins_limit` | Maximum number of joins that the optimizer will attempt to reorder when searching for an optimal query execution plan. <br/><br/>For more information, see [Join reordering]({% link {{ page.version.version }}/cost-based-optimizer.md %}#join-reordering). | `8` | Yes | Yes |
 | <a id="require-explicit-primary-keys"></a> `require_explicit_primary_keys` | If `on`, CockroachDB throws an error for all tables created without an explicit primary key defined. | `off` | Yes | Yes |
 | <a id="search-path"></a> `search_path` | A list of schemas that will be searched to resolve unqualified table or function names. <br/>For more details, see [SQL name resolution]({% link {{ page.version.version }}/sql-name-resolution.md %}). | `public` | Yes | Yes |
-| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
+| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, [`sql_sequence_cached_node`]({% link {{ page.version.version }}/create-sequence.md %}#per-node-cache), and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached` or `sql_sequence_cached_node`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
 | <a id="server-version"></a> `server_version` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | No | Yes |
 | <a id="server-version-num"></a> `server_version_num` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | Yes | Yes |
 | <a id="session-id"></a> `session_id` | The ID of the current session. | Session-dependent | No | Yes |

src/current/_includes/v24.3/misc/session-vars.md

@@ -65,7 +65,7 @@
 | <a id="reorder-joins-limit"></a> `reorder_joins_limit` | Maximum number of joins that the optimizer will attempt to reorder when searching for an optimal query execution plan. <br/><br/>For more information, see [Join reordering]({% link {{ page.version.version }}/cost-based-optimizer.md %}#join-reordering). | `8` | Yes | Yes |
 | <a id="require-explicit-primary-keys"></a> `require_explicit_primary_keys` | If `on`, CockroachDB throws an error for all tables created without an explicit primary key defined. | `off` | Yes | Yes |
 | <a id="search-path"></a> `search_path` | A list of schemas that will be searched to resolve unqualified table or function names. <br/>For more details, see [SQL name resolution]({% link {{ page.version.version }}/sql-name-resolution.md %}). | `public` | Yes | Yes |
-| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
+| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, [`sql_sequence_cached_node`]({% link {{ page.version.version }}/create-sequence.md %}#per-node-cache), and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached` or `sql_sequence_cached_node`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
 | <a id="server-version"></a> `server_version` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | No | Yes |
 | <a id="server-version-num"></a> `server_version_num` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | Yes | Yes |
 | <a id="session-id"></a> `session_id` | The ID of the current session. | Session-dependent | No | Yes |

src/current/_includes/v25.2/misc/session-vars.md

@@ -69,7 +69,7 @@
 | <a id="reorder-joins-limit"></a> `reorder_joins_limit` | Maximum number of joins that the optimizer will attempt to reorder when searching for an optimal query execution plan. <br/><br/>For more information, see [Join reordering]({% link {{ page.version.version }}/cost-based-optimizer.md %}#join-reordering). | `8` | Yes | Yes |
 | <a id="require-explicit-primary-keys"></a> `require_explicit_primary_keys` | If `on`, CockroachDB throws an error for all tables created without an explicit primary key defined. | `off` | Yes | Yes |
 | <a id="search-path"></a> `search_path` | A list of schemas that will be searched to resolve unqualified table or function names. <br/>For more details, see [SQL name resolution]({% link {{ page.version.version }}/sql-name-resolution.md %}). | `public` | Yes | Yes |
-| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
+| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, [`sql_sequence_cached_node`]({% link {{ page.version.version }}/create-sequence.md %}#per-node-cache), and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached` or `sql_sequence_cached_node`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
 | <a id="server-version"></a> `server_version` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | No | Yes |
 | <a id="server-version-num"></a> `server_version_num` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | Yes | Yes |
 | <a id="session-id"></a> `session_id` | The ID of the current session. | Session-dependent | No | Yes |

src/current/_includes/v25.3/misc/session-vars.md

@@ -69,7 +69,7 @@
 | <a id="reorder-joins-limit"></a> `reorder_joins_limit` | Maximum number of joins that the optimizer will attempt to reorder when searching for an optimal query execution plan. <br/><br/>For more information, see [Join reordering]({% link {{ page.version.version }}/cost-based-optimizer.md %}#join-reordering). | `8` | Yes | Yes |
 | <a id="require-explicit-primary-keys"></a> `require_explicit_primary_keys` | If `on`, CockroachDB throws an error for all tables created without an explicit primary key defined. | `off` | Yes | Yes |
 | <a id="search-path"></a> `search_path` | A list of schemas that will be searched to resolve unqualified table or function names. <br/>For more details, see [SQL name resolution]({% link {{ page.version.version }}/sql-name-resolution.md %}). | `public` | Yes | Yes |
-| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
+| <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, [`sql_sequence_cached_node`]({% link {{ page.version.version }}/create-sequence.md %}#per-node-cache), and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached` or `sql_sequence_cached_node`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
 | <a id="server-version"></a> `server_version` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | No | Yes |
 | <a id="server-version-num"></a> `server_version_num` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | Yes | Yes |
 | <a id="session-id"></a> `session_id` | The ID of the current session. | Session-dependent | No | Yes |

src/current/v24.1/create-sequence.md

@@ -38,6 +38,7 @@ The user must have the `CREATE` [privilege]({% link {{ page.version.version }}/s
 `RESTART [WITH]` | Sets `nextval` to the specified number, or back to the original `START` value.
 `NO CYCLE` | All sequences are set to `NO CYCLE` and the sequence will not wrap.
 `CACHE` | The number of sequence values to cache in memory for reuse in the session. A cache size of `1` means that there is no cache, and cache sizes of less than `1` are not valid.<br><br>**Default:** `1` (sequences are not cached by default)
+`PER NODE CACHE` <a name="per-node-cache"></a> | The number of sequence values to cache in memory at the node level. All sessions on the node share the same cache, which can be concurrently accessed, and which reduces the chance of creating large gaps between generated IDs. A cache size of `1` means that there is no cache, and cache sizes of less than `1` are not valid.<br><br>**Default:** `256` (controlled by the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `sql.defaults.serial_sequences_cache_size` when the [session variable]({% link {{ page.version.version }}/set-vars.md %}) `serial_normalization` is set to `sql_sequence_cached_node`)
 `OWNED BY column_name` <a name="owned-by"></a> | Associates the sequence to a particular column. If that column or its parent table is dropped, the sequence will also be dropped.<br>Specifying an owner column with `OWNED BY` replaces any existing owner column on the sequence. To remove existing column ownership on the sequence and make the column free-standing, specify `OWNED BY NONE`.<br><br>**Default:** `NONE`
 `opt_temp` | Defines the sequence as a session-scoped temporary sequence. For more information, see [Temporary sequences](#temporary-sequences).
 
@@ -296,6 +297,29 @@ For example, to cache 10 sequence values in memory:
 (1 row)
 ~~~
 
+### Cache sequence values per node
+
+For improved performance, use the `PER NODE CACHE` clause to cache sequence values in memory at the node level.
+
+For example, to cache 10 sequence values per node:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE SEQUENCE customer_seq_node_cached PER NODE CACHE 10;
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SHOW CREATE customer_seq_node_cached;
+~~~
+
+~~~
+      table_name      |                                                create_statement
+----------------------+------------------------------------------------------------------------------------------------------------------
+  customer_seq_node_cached | CREATE SEQUENCE public.customer_seq_node_cached MINVALUE 1 MAXVALUE 9223372036854775807 INCREMENT 1 START 1 PER NODE CACHE 10
+(1 row)
+~~~
+
 ## See also
 
 - [`ALTER SEQUENCE`]({% link {{ page.version.version }}/alter-sequence.md %})

src/current/v24.3/create-sequence.md

@@ -38,6 +38,7 @@ The user must have the `CREATE` [privilege]({% link {{ page.version.version }}/s
 `RESTART [WITH]` | Sets `nextval` to the specified number, or back to the original `START` value.
 `NO CYCLE` | All sequences are set to `NO CYCLE` and the sequence will not wrap.
 `CACHE` | The number of sequence values to cache in memory for reuse in the session. A cache size of `1` means that there is no cache, and cache sizes of less than `1` are not valid.<br><br>**Default:** `1` (sequences are not cached by default)
+`PER NODE CACHE` <a name="per-node-cache"></a> | The number of sequence values to cache in memory at the node level. All sessions on the node share the same cache, which can be concurrently accessed, and which reduces the chance of creating large gaps between generated IDs. A cache size of `1` means that there is no cache, and cache sizes of less than `1` are not valid.<br><br>**Default:** `256` (controlled by the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `sql.defaults.serial_sequences_cache_size` when the [session variable]({% link {{ page.version.version }}/set-vars.md %}) `serial_normalization` is set to `sql_sequence_cached_node`)
 `OWNED BY column_name` <a name="owned-by"></a> | Associates the sequence to a particular column. If that column or its parent table is dropped, the sequence will also be dropped.<br>Specifying an owner column with `OWNED BY` replaces any existing owner column on the sequence. To remove existing column ownership on the sequence and make the column free-standing, specify `OWNED BY NONE`.<br><br>**Default:** `NONE`
 `opt_temp` | Defines the sequence as a session-scoped temporary sequence. For more information, see [Temporary sequences](#temporary-sequences).
 
@@ -296,6 +297,29 @@ For example, to cache 10 sequence values in memory:
 (1 row)
 ~~~
 
+### Cache sequence values per node
+
+For improved performance, use the `PER NODE CACHE` clause to cache sequence values in memory at the node level.
+
+For example, to cache 10 sequence values per node:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE SEQUENCE customer_seq_node_cached PER NODE CACHE 10;
+~~~
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SHOW CREATE customer_seq_node_cached;
+~~~
+
+~~~
+      table_name      |                                                create_statement
+----------------------+------------------------------------------------------------------------------------------------------------------
+  customer_seq_node_cached | CREATE SEQUENCE public.customer_seq_node_cached MINVALUE 1 MAXVALUE 9223372036854775807 INCREMENT 1 START 1 PER NODE CACHE 10
+(1 row)
+~~~
+
 ## See also
 
 - [`ALTER SEQUENCE`]({% link {{ page.version.version }}/alter-sequence.md %})