[
https://issues.apache.org/jira/browse/DERBY-5697?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13259744#comment-13259744
]
Rick Hillegas commented on DERBY-5697:
--------------------------------------
Thanks, Kim. These changes look good. +1
> Doc changes to account for correctness fixes for sequences
> ----------------------------------------------------------
>
> Key: DERBY-5697
> URL: https://issues.apache.org/jira/browse/DERBY-5697
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Affects Versions: 10.9.0.0
> Reporter: Rick Hillegas
> Assignee: Kim Haase
> Attachments: DERBY-5697.diff, DERBY-5697.stat, DERBY-5697.zip
>
>
> As a result of the correctness fixes made by DERBY-5493 and DERBY-5494, we
> should adjust the user documentation for sequences. I recommend the following
> changes:
> 1) Reference Guide
> a) Add a section for a new system function. This function lets users observe
> the instantaneous current value of a sequence generator without having to
> query SYSSEQUENCES. Querying SYSSEQUENCES didn't actually return the current
> value, it only returned an upper bound on that value, viz., the end of the
> chunk of sequence values which had been pre-allocated but not actually used.
> The new function shows you the very next value which will be returned by a
> NEXT VALUE FOR clause. Users should never directly query SYSSEQUENCES because
> that will cause sequence generator concurrency to slow down to a crawl.
> Syntax
> BIGINT SYSCS_UTIL.SYSCS_PEEK_AT_SEQUENCE(IN SCHEMANAME VARCHAR(128), IN
> SEQUENCENAME VARCHAR(128))
> As with all system functions, schema and object name arguments are
> case-sensitive.
> Execute privileges
> By default, all users have execute privileges on this function.
> b) SYSSEQUENCES system table
> The Contents description for SYSSEQUENCES.CURRENTVALUE needs to be changed to
> make a couple points: This is not the actual next value for the sequence
> generator. That value can be obtained by calling SYSCS_PEEK_AT_SEQUENCE().
> SYSSEQUENCES.CURRENTVALUE holds the end of the range of values which have
> been pre-allocated in order to boost concurrency. Users should not directly
> query SYSSEQUENCES because that will slow down the performance of sequence
> generators. Instead, users should call SYSCS_PEEK_AT_SEQUENCE().
> c) derby.language.sequence.preallocator
> The default value of this property has changed from 20 to 100.
> In addition, I think that we should point out that if the database is shut
> down gracefully, then Derby should not leak unused, preallocated values; they
> will be thrown away and the sequence generator will pick up where it left
> off, once the database re-boots. However, if the database comes down
> ungracefully, then unused, preallocated values will be leaked: when the
> database comes up again, the sequence generator will skip the unused,
> preallocated values; this will leave a gap between the last NEXT VALUE FOR
> (issued before the database came down ungracefully) and the next NEXT VALUE
> FOR (issued after the database re-boots).
> 2) Tuning Guide
> Maybe we should add a small section explaining how to boost the concurrency
> of sequences:
> a) Don't query SYSSEQUENCES directly. Instead, use SYSCS_PEEK_AT_SEQUENCE().
> b) Adjusting derby.language.sequence.preallocator may boost your concurrency.
> However, you should pay special attention to bringing down the database
> gracefully in order to not leak unused, preallocated values. See the
> Reference Manual section on derby.language.sequence.preallocator.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
