From 81f061de44b7440ca6691f2d794dfa2202ae0128 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Tue, 6 Jan 2026 15:36:33 -0500 Subject: [PATCH 1/2] Clarify sequence bumps perform replicated writes This was not stated explicitly enough in the `CREATE SEQUENCE` docs and led to performance issues for a customer who had migrated from PG with sequence usage. Fixes DOC-15768 --- src/current/v26.1/create-sequence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v26.1/create-sequence.md b/src/current/v26.1/create-sequence.md index b95b086cdd7..4159241a173 100644 --- a/src/current/v26.1/create-sequence.md +++ b/src/current/v26.1/create-sequence.md @@ -11,7 +11,7 @@ The `CREATE SEQUENCE` [statement]({% link {{ page.version.version }}/sql-stateme ## Considerations -- Using a sequence is slower than [auto-generating unique IDs with the `gen_random_uuid()`, `uuid_v4()` or `unique_rowid()` built-in functions]({% link {{ page.version.version }}/sql-faqs.md %}#how-do-i-auto-generate-unique-row-ids-in-cockroachdb) and is likely to cause performance problems due to [hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}). Incrementing a sequence requires a write to persistent storage, whereas auto-generating a unique ID does not. Therefore, use auto-generated unique IDs unless an incremental sequence is preferred or required. For more information, see [Unique ID best practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#unique-id-best-practices). +- Using a sequence is slower than [auto-generating unique IDs with the `gen_random_uuid()`, `uuid_v4()` or `unique_rowid()` built-in functions]({% link {{ page.version.version }}/sql-faqs.md %}#how-do-i-auto-generate-unique-row-ids-in-cockroachdb) and is likely to cause performance problems due to [hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}). Incrementing a sequence requires a write to persistent storage. In CockroachDB, all writes are [replicated and must reach a write quorum]({% link {{ page.version.version }}/architecture/replication-layer.md %}). This means that in [multi-region deployments]({% link {{ page.version.version }}/multiregion-overview.md %}), this can add cross-region latency (for example, in a [region survival]({% link {{ page.version.version }}/multiregion-survival-goals.md %}) configuration) and can become a throughput bottleneck for write-heavy workloads. Auto-generating a unique ID does not require a replicated write. Therefore, use auto-generated unique IDs unless an incremental sequence is preferred or required. For more information, see [Unique ID best practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#unique-id-best-practices). - A column that uses a sequence can have a gap in the sequence values if a transaction advances the sequence and is then rolled back. Sequence updates are committed immediately and aren't rolled back along with their containing transaction. This is done to avoid blocking concurrent transactions that use the same sequence. - {% include {{page.version.version}}/performance/use-hash-sharded-indexes.md %} - By default, you cannot create sequences that are [owned by]({% link {{ page.version.version }}/security-reference/authorization.md %}#object-ownership) columns in tables in other databases. You can enable such sequence creation by setting the `sql.cross_db_sequence_owners.enabled` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to `true`. From 46c0d0e3f553f0826e8ba4c87b5133b479cc255f Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 7 Jan 2026 14:32:17 -0500 Subject: [PATCH 2/2] Update with rafiss feedback (1) --- src/current/v26.1/create-sequence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v26.1/create-sequence.md b/src/current/v26.1/create-sequence.md index 4159241a173..558e10a77e5 100644 --- a/src/current/v26.1/create-sequence.md +++ b/src/current/v26.1/create-sequence.md @@ -11,7 +11,7 @@ The `CREATE SEQUENCE` [statement]({% link {{ page.version.version }}/sql-stateme ## Considerations -- Using a sequence is slower than [auto-generating unique IDs with the `gen_random_uuid()`, `uuid_v4()` or `unique_rowid()` built-in functions]({% link {{ page.version.version }}/sql-faqs.md %}#how-do-i-auto-generate-unique-row-ids-in-cockroachdb) and is likely to cause performance problems due to [hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}). Incrementing a sequence requires a write to persistent storage. In CockroachDB, all writes are [replicated and must reach a write quorum]({% link {{ page.version.version }}/architecture/replication-layer.md %}). This means that in [multi-region deployments]({% link {{ page.version.version }}/multiregion-overview.md %}), this can add cross-region latency (for example, in a [region survival]({% link {{ page.version.version }}/multiregion-survival-goals.md %}) configuration) and can become a throughput bottleneck for write-heavy workloads. Auto-generating a unique ID does not require a replicated write. Therefore, use auto-generated unique IDs unless an incremental sequence is preferred or required. For more information, see [Unique ID best practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#unique-id-best-practices). +- Using a sequence is slower than [auto-generating unique IDs with the `gen_random_uuid()`, `uuid_v4()` or `unique_rowid()` built-in functions]({% link {{ page.version.version }}/sql-faqs.md %}#how-do-i-auto-generate-unique-row-ids-in-cockroachdb) and is likely to cause performance problems due to [hotspots]({% link {{ page.version.version }}/understand-hotspots.md %}). Incrementing a sequence requires a write to persistent storage. In CockroachDB, all writes are [replicated and must reach a write quorum]({% link {{ page.version.version }}/architecture/replication-layer.md %}). This means that in [multi-region deployments]({% link {{ page.version.version }}/multiregion-overview.md %}), this can add cross-region latency (for example, in a [region survival]({% link {{ page.version.version }}/multiregion-survival-goals.md %}) configuration) and can become a throughput bottleneck for write-heavy workloads. [Cached sequences](#cache-sequence-values-in-memory-per-node) can reduce the frequency of these writes, though gaps in sequence values may occur if cached values are lost. Auto-generating a unique ID does not require a replicated write. Therefore, use auto-generated unique IDs unless an incremental sequence is preferred or required. For more information, see [Unique ID best practices]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#unique-id-best-practices). - A column that uses a sequence can have a gap in the sequence values if a transaction advances the sequence and is then rolled back. Sequence updates are committed immediately and aren't rolled back along with their containing transaction. This is done to avoid blocking concurrent transactions that use the same sequence. - {% include {{page.version.version}}/performance/use-hash-sharded-indexes.md %} - By default, you cannot create sequences that are [owned by]({% link {{ page.version.version }}/security-reference/authorization.md %}#object-ownership) columns in tables in other databases. You can enable such sequence creation by setting the `sql.cross_db_sequence_owners.enabled` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to `true`.