Clarify sequence bumps perform replicated writes #22039
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
Files changed: |
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
rafiss
approved these changes
Jan 7, 2026
src/current/v26.1/create-sequence.md
Outdated
| ## 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). |
Contributor
There was a problem hiding this comment.
this lgtm!
it may be worth mentioning something about cached sequences too. something to the effect of: [Cached sequences](#link-to-cached-sequence-docs) can reduce the frequency of these writes, though gaps in sequence values may occur if cached values are lost
(These will perform better than normal sequences, but not as good as the ID generation functions)
Contributor
Author
|
Rafi Shamim ***@***.***> writes:
this lgtm!
sweet thanks!
it may be worth mentioning something about cached sequences too.
something to the effect of: [Cached sequences]
(#link-to-cached-sequence-docs) can reduce the frequency of these
writes, though gaps in sequence values may occur if cached values are
lost
(These will perform better than normal sequences, but not as good as
the ID generation functions)
updated to add your suggested language with the link to cached
sequences!
thanks for the review Rafi!
|
Contributor
Author
|
PS @rafiss after docs team review I am planning to backport this change to the docs for all supported versions v23.2 and later - please let me know if you disagree for any reason! i suspect it's still true on those older versions too, right? |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This was not stated explicitly enough in the
CREATE SEQUENCEdocs and led to performance issues for a customer who had migrated from PG with sequence usage.Fixes DOC-15768