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
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
