Derby
  1. Derby
  2. DERBY-4259

Document database property for determining database format version

    Details

    • Type: Improvement Improvement
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.6.1.0
    • Fix Version/s: 10.10.1.1
    • Component/s: Documentation
    • Labels:
      None

      Description

      It would be useful to have a public interface for determining the database format when running in soft upgrade mode. In the derby-user thread:
      http://www.nabble.com/Hard-upgrade-failing--td23826558.html#a23835534
      Evan pointed out he was using an undocumented property 'DataDictionaryVersion' for this purpose, but this is not ideal because it does not conform to the normal derby.* naming convention and is not documented.

      Discussion in DERBY-4255 determined that there are not currently DatabaseMetaData methods that achieve the same result.

      1. DERBY-4259.diff
        4 kB
        Kim Haase
      2. DERBY-4259.stat
        0.1 kB
        Kim Haase
      3. DERBY-4259.zip
        8 kB
        Kim Haase
      4. DERBY-4259-2.diff
        4 kB
        Kim Haase
      5. DERBY-4259-2.zip
        8 kB
        Kim Haase
      6. DERBY-4259-3.diff
        4 kB
        Kim Haase
      7. DERBY-4259-3.zip
        8 kB
        Kim Haase
      8. DERBY-4259-4.diff
        1 kB
        Kim Haase
      9. rrefproperdatadictversion.html
        14 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Knut Anders Hatlen added a comment -

          In DERBY-5818 it was suggested that simply documenting DataDictionaryVersion would be a fine start. Documenting a property that follows a non-standard naming convention probably doesn't add a lot more entropy than adding a new property with the same function would.

          Show
          Knut Anders Hatlen added a comment - In DERBY-5818 it was suggested that simply documenting DataDictionaryVersion would be a fine start. Documenting a property that follows a non-standard naming convention probably doesn't add a lot more entropy than adding a new property with the same function would.
          Hide
          Kim Haase added a comment -

          Would it make sense to convert this issue to a doc issue for documenting the DataDictionaryVersion property? If so, I can do this and pick up the task. I gather it doesn't conform to the usual property naming convention ("derby.xxx.propertyName").

          Alternately, I can create a new issue for the documentation and leave this one as is.

          Show
          Kim Haase added a comment - Would it make sense to convert this issue to a doc issue for documenting the DataDictionaryVersion property? If so, I can do this and pick up the task. I gather it doesn't conform to the usual property naming convention ("derby.xxx.propertyName"). Alternately, I can create a new issue for the documentation and leave this one as is.
          Hide
          Rick Hillegas added a comment -

          Hi Kim,

          Now that DERBY-5838 has been fixed, I think it's OK to document the DataDictionaryVersion property. I recommend considering the following points:

          o The actual value of DataDictionaryVersion can be a little confusing, depending on whether the database has been soft-upgraded. The possible values of this property are discussed on DERBY-5818.

          o I think it's worth mentioning that you can't change the value of this property. This diverges from the behavior of most other properties.

          Thanks,
          -Rick

          Show
          Rick Hillegas added a comment - Hi Kim, Now that DERBY-5838 has been fixed, I think it's OK to document the DataDictionaryVersion property. I recommend considering the following points: o The actual value of DataDictionaryVersion can be a little confusing, depending on whether the database has been soft-upgraded. The possible values of this property are discussed on DERBY-5818 . o I think it's worth mentioning that you can't change the value of this property. This diverges from the behavior of most other properties. Thanks, -Rick
          Hide
          Kim Haase added a comment -

          Converting to a documentation issue.

          Show
          Kim Haase added a comment - Converting to a documentation issue.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-4259.diff, DERBY-4259.stat, and DERBY-4259.zip, with changes as follows:

          A src/ref/rrefproperdatadictversion.dita
          M src/ref/crefproper22250.dita
          M src/ref/refderby.ditamap

          Please let me know what needs fixing – I'm not at all sure the info about the version values is right.

          Thanks!

          Show
          Kim Haase added a comment - Attaching DERBY-4259 .diff, DERBY-4259 .stat, and DERBY-4259 .zip, with changes as follows: A src/ref/rrefproperdatadictversion.dita M src/ref/crefproper22250.dita M src/ref/refderby.ditamap Please let me know what needs fixing – I'm not at all sure the info about the version values is right. Thanks!
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. This looks good. I recommend adding some more verbiage to punch up the fact that this is the rev level of the data on disk, not the rev level of the Derby jar files.

          rrefproperdatadictversion

          I would re-word the first paragraph slightly:

          "Shows the version of the on-disk data in the database. This is the first two (major and minor) numbers in a Derby release identifier. For newly created databases, this is the release identifier of the Derby engine jar used to create the database. For hard-upgraded databases, this is the release identifier of the Derby engine jar used to hard-upgrade the database."

          Thanks,
          -Rick

          Show
          Rick Hillegas added a comment - Thanks, Kim. This looks good. I recommend adding some more verbiage to punch up the fact that this is the rev level of the data on disk, not the rev level of the Derby jar files. rrefproperdatadictversion I would re-word the first paragraph slightly: "Shows the version of the on-disk data in the database. This is the first two (major and minor) numbers in a Derby release identifier. For newly created databases, this is the release identifier of the Derby engine jar used to create the database. For hard-upgraded databases, this is the release identifier of the Derby engine jar used to hard-upgrade the database." Thanks, -Rick
          Hide
          Kim Haase added a comment -

          Thanks, Rick – that's exactly the feedback I was hoping for. Attaching DERBY-4259-2.diff and DERBY-4259-2.zip, with the changes you suggest.

          Show
          Kim Haase added a comment - Thanks, Rick – that's exactly the feedback I was hoping for. Attaching DERBY-4259 -2.diff and DERBY-4259 -2.zip, with the changes you suggest.
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. Looks great except for the trailing "Shows the release of Derby for the database." at the end of the first paragraph in rrefproperdatadictversion. Thanks.

          Show
          Rick Hillegas added a comment - Thanks, Kim. Looks great except for the trailing "Shows the release of Derby for the database." at the end of the first paragraph in rrefproperdatadictversion. Thanks.
          Hide
          Kim Haase added a comment -

          Argh! Haste makes waste. Here's yet another try: DERBY-4259-3.diff and DERBY-4259-3.zip.

          Show
          Kim Haase added a comment - Argh! Haste makes waste. Here's yet another try: DERBY-4259 -3.diff and DERBY-4259 -3.zip.
          Hide
          Rick Hillegas added a comment -

          Thanks, Kim. Looks great. +1

          Show
          Rick Hillegas added a comment - Thanks, Kim. Looks great. +1
          Hide
          Kim Haase added a comment -

          Thanks, Rick.

          Committed patch DERBY-4259-3.diff to documentation trunk at revision 1438673.

          Show
          Kim Haase added a comment - Thanks, Rick. Committed patch DERBY-4259 -3.diff to documentation trunk at revision 1438673.
          Hide
          Dag H. Wanvik added a comment -

          Sorry for chiming in late on this, but reading the description i was left with two questions:

          "With is the value for not-so-newly-created data bases ? What is the value for soft upgraded databases? Obvious to us, I'm sure, but reading the description it seems as though not all cases are described... At a minimum it requires the reader to understand what hard upgrading means, so a link to its definition would be good. Since the description relates the property to the version of the jar it would be good to state explicitly that the DD inherits the version of the jar that either a) created the database or b) did the hard upgrade which will upgrade the dictionary format (and hence version).

          Show
          Dag H. Wanvik added a comment - Sorry for chiming in late on this, but reading the description i was left with two questions: "With is the value for not-so-newly-created data bases ? What is the value for soft upgraded databases? Obvious to us, I'm sure, but reading the description it seems as though not all cases are described... At a minimum it requires the reader to understand what hard upgrading means, so a link to its definition would be good. Since the description relates the property to the version of the jar it would be good to state explicitly that the DD inherits the version of the jar that either a) created the database or b) did the hard upgrade which will upgrade the dictionary format (and hence version).
          Hide
          Kim Haase added a comment -

          Thanks for catching this, Dag.

          I notice that in the Developer's Guide we talk about a "full upgrade" rather than a "hard upgrade" (though the opposite is still "soft").

          I should probably refer to the "upgrade=true attribute" topic, which then refers to the appropriate section of the Dev Guide.

          So a soft upgrade does not change the DataDictionaryVersion, unlike a full upgrade?

          I'll file another suggested patch.

          Show
          Kim Haase added a comment - Thanks for catching this, Dag. I notice that in the Developer's Guide we talk about a "full upgrade" rather than a "hard upgrade" (though the opposite is still "soft"). I should probably refer to the "upgrade=true attribute" topic, which then refers to the appropriate section of the Dev Guide. So a soft upgrade does not change the DataDictionaryVersion, unlike a full upgrade? I'll file another suggested patch.
          Hide
          Kim Haase added a comment -

          Attaching DERBY-4259-4.diff and rrefproperdatadictversion.html, with fixes to that topic:

          M src/ref/rrefproperdatadictversion.dita

          I tried to tidy up some language that seemed a little awkward, in addition to clarifying (I hope) the upgrade situation and adding a cross-reference.

          Show
          Kim Haase added a comment - Attaching DERBY-4259 -4.diff and rrefproperdatadictversion.html, with fixes to that topic: M src/ref/rrefproperdatadictversion.dita I tried to tidy up some language that seemed a little awkward, in addition to clarifying (I hope) the upgrade situation and adding a cross-reference.
          Hide
          Dag H. Wanvik added a comment -

          > So a soft upgrade does not change the DataDictionaryVersion, unlike a full upgrade?

          Yes, correct. Thanks, Kim! Looks good. +1

          Show
          Dag H. Wanvik added a comment - > So a soft upgrade does not change the DataDictionaryVersion, unlike a full upgrade? Yes, correct. Thanks, Kim! Looks good. +1
          Hide
          Kim Haase added a comment -

          Thanks, Dag!

          Committed patch DERBY-4259-4.diff to documentation trunk at revision 1439926.

          Show
          Kim Haase added a comment - Thanks, Dag! Committed patch DERBY-4259 -4.diff to documentation trunk at revision 1439926.
          Hide
          Kim Haase added a comment -

          Closing, since changes have appeared in Latest Alpha Manuals.

          Show
          Kim Haase added a comment - Closing, since changes have appeared in Latest Alpha Manuals.

            People

            • Assignee:
              Kim Haase
              Reporter:
              Kathey Marsden
            • Votes:
              0 Vote for this issue
              Watchers:
              4 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development