Derby
  1. Derby
  2. DERBY-5203

Documentation of drop=true attribute contains error

    Details

    • Type: Bug Bug
    • Status: Closed
    • Priority: Minor Minor
    • Resolution: Fixed
    • Affects Version/s: 10.8.1.2
    • Fix Version/s: 10.8.2.2, 10.9.1.0
    • Component/s: Documentation
    • Labels:
      None

      Description

      The Reference Manual topic on the drop=true attribute, rrefattribdrop.dita, contains the statement,

      "This attribute, like shutdown=true, cannot be combined with other attributes."

      This used to be true, but with the addition of the deregister attribute, which must be combined with shutdown=true, it is now incorrect.

      The sentence should be changed to say only,

      "This attribute cannot be combined with other attributes."

      (I'm assuming that the deregister attribute doesn't apply to dropping an in-memory database, since it's specific to the embedded driver. Please let me know if this isn't the case.)

      1. rrefattribdrop.html
        4 kB
        Kim Haase
      2. rrefattribdrop.html
        4 kB
        Kim Haase
      3. rrefattribdrop.html
        4 kB
        Kim Haase
      4. rrefattrib16471.html
        5 kB
        Kim Haase
      5. DERBY-5203-3.diff
        2 kB
        Kim Haase
      6. DERBY-5203-2.stat
        0.1 kB
        Kim Haase
      7. DERBY-5203-2.diff
        2 kB
        Kim Haase
      8. DERBY-5203.stat
        0.0 kB
        Kim Haase
      9. DERBY-5203.diff
        0.6 kB
        Kim Haase

        Issue Links

          Activity

          Hide
          Kim Haase added a comment -

          Attaching DERBY-5203.diff, DERBY-5203.stat, and rrefattribdrop.html, with a very small change to

          M src/ref/rrefattribdrop.dita

          I will commit this patch in a couple of days unless I hear otherwise.

          Show
          Kim Haase added a comment - Attaching DERBY-5203 .diff, DERBY-5203 .stat, and rrefattribdrop.html, with a very small change to M src/ref/rrefattribdrop.dita I will commit this patch in a couple of days unless I hear otherwise.
          Hide
          Knut Anders Hatlen added a comment -

          I think you're right that the deregister attribute isn't meaningful when an in-memory database (or any database for that matter) is specified in the URL, since deregistering of the driver only happens when you shut down the engine.

          I'm not sure how accurate the sentence "This attribute cannot be combined with other attributes." is, though. The drop attribute certainly can be combined with other attributes (although it doesn't necessarily make sense). For example the following works:

          ij> connect 'jdbc:derby:memory:db;drop=true;deregister=true;user=test;password=xyz';
          ERROR 08006: Database 'memory:db' dropped.

          And if authentication is enabled, combining it with other attributes is actually required:

          ij> connect 'jdbc:derby:memory:db;drop=true';
          ERROR 08004: Connection authentication failure occurred. Reason: Invalid authentication..
          ij> connect 'jdbc:derby:memory:db;drop=true;user=abc;password=def';
          ERROR 08006: Database 'memory:db' dropped.

          Show
          Knut Anders Hatlen added a comment - I think you're right that the deregister attribute isn't meaningful when an in-memory database (or any database for that matter) is specified in the URL, since deregistering of the driver only happens when you shut down the engine. I'm not sure how accurate the sentence "This attribute cannot be combined with other attributes." is, though. The drop attribute certainly can be combined with other attributes (although it doesn't necessarily make sense). For example the following works: ij> connect 'jdbc:derby:memory:db;drop=true;deregister=true;user=test;password=xyz'; ERROR 08006: Database 'memory:db' dropped. And if authentication is enabled, combining it with other attributes is actually required: ij> connect 'jdbc:derby:memory:db;drop=true'; ERROR 08004: Connection authentication failure occurred. Reason: Invalid authentication.. ij> connect 'jdbc:derby:memory:db;drop=true;user=abc;password=def'; ERROR 08006: Database 'memory:db' dropped.
          Hide
          Knut Anders Hatlen added a comment -

          I forgot to say +1 to the patch. So here it is: +1

          The change made by the patch is orthogonal to the question of whether or not drop=true can be combined with other attributes, and it does make the sentence more correct.

          Show
          Knut Anders Hatlen added a comment - I forgot to say +1 to the patch. So here it is: +1 The change made by the patch is orthogonal to the question of whether or not drop=true can be combined with other attributes, and it does make the sentence more correct.
          Hide
          Kim Haase added a comment -

          Thanks for the +1, but I think I should provide a revised patch that provides correct information! I will see what I can do about that.

          I think shutdown=true must also be accompanied by a username and password if authentication is enabled, correct? The examples in the Dev Guide show this.

          Show
          Kim Haase added a comment - Thanks for the +1, but I think I should provide a revised patch that provides correct information! I will see what I can do about that. I think shutdown=true must also be accompanied by a username and password if authentication is enabled, correct? The examples in the Dev Guide show this.
          Hide
          Kim Haase added a comment -

          Thanks again for checking this over carefully, Knut. I hope this isn't mission creep, but I figure I may as well correct the shutdown topic as well as the drop topic. I borrowed the language about authentication and SQL authorization from some other topics (startmaster, for instance).

          Attaching DERBY-5203-2.diff, DERBY-5203-2.stat, rrefattribdrop.html, and refattrib16471.html, with hopefully correct information about combining the attributes with others.

          Show
          Kim Haase added a comment - Thanks again for checking this over carefully, Knut. I hope this isn't mission creep, but I figure I may as well correct the shutdown topic as well as the drop topic. I borrowed the language about authentication and SQL authorization from some other topics (startmaster, for instance). Attaching DERBY-5203 -2.diff, DERBY-5203 -2.stat, rrefattribdrop.html, and refattrib16471.html, with hopefully correct information about combining the attributes with others.
          Hide
          Knut Anders Hatlen added a comment -

          Thanks, Kim. The suggested wording looks clear and fine to me. With the added information about the user and password attributes, perhaps the sentence "This attribute can be combined with other attributes." becomes redundant and could be removed? In any case, +1 to the patch.

          Show
          Knut Anders Hatlen added a comment - Thanks, Kim. The suggested wording looks clear and fine to me. With the added information about the user and password attributes, perhaps the sentence "This attribute can be combined with other attributes." becomes redundant and could be removed? In any case, +1 to the patch.
          Hide
          Kim Haase added a comment -

          Thanks, Knut – you're right that that sentence is redundant. Attaching DERBY-5203-3.diff and a revised rrefattribdrop.html. I'll commit this shortly.

          Show
          Kim Haase added a comment - Thanks, Knut – you're right that that sentence is redundant. Attaching DERBY-5203 -3.diff and a revised rrefattribdrop.html. I'll commit this shortly.
          Hide
          Kim Haase added a comment -

          Committed patch DERBY-5203-3.diff to documentation trunk at revision 1097973.
          Merged to 10.8 doc branch at revision 1097977.

          Show
          Kim Haase added a comment - Committed patch DERBY-5203 -3.diff to documentation trunk at revision 1097973. Merged to 10.8 doc branch at revision 1097977.
          Hide
          Dag H. Wanvik added a comment -

          > I think shutdown=true must also be accompanied by a username and password if authentication is enabled, correct?

          Authentication and SQL authorization as far as i recall, we didn't want to break compatibility for existing usage with only authentication, which has been around longer.

          Show
          Dag H. Wanvik added a comment - > I think shutdown=true must also be accompanied by a username and password if authentication is enabled, correct? Authentication and SQL authorization as far as i recall, we didn't want to break compatibility for existing usage with only authentication, which has been around longer.
          Hide
          Kim Haase added a comment -

          Oops, not "or"? I borrowed the language from http://db.apache.org/derby/docs/dev/ref/rrefattribstartmaster.html and its ilk. Perhaps for newer features like replication and drop it is "or" but for shutdown it is "and"?

          Show
          Kim Haase added a comment - Oops, not "or"? I borrowed the language from http://db.apache.org/derby/docs/dev/ref/rrefattribstartmaster.html and its ilk. Perhaps for newer features like replication and drop it is "or" but for shutdown it is "and"?
          Hide
          Knut Anders Hatlen added a comment -

          Thanks, Dag. I had forgotten about that. It's actually a bit more
          complicated:

          1) Authentication only:

          • System shutdown can be performed by any user and without providing
            credentials.
          • Database shutdown can be performed by any user, but credentials are
            required.

          2) SQL authorization only:

          • System shutdown can be performed by any user without providing
            credentials.
          • Database shutdown can be performed by any user without providing
            credentials.

          3) Authentication and SQL authorization:

          • System shutdown requires credentials, but it can be performed by any
            user.
          • Database shutdown requires credentials, and it can only be performed
            by the DBO.

          For drop=true, we have this:

          1) Authentication only:

          • Databases can be dropped by any user, but credentials are required.

          2) SQL authorization only:

          • Databases can be dropped by any user without providing credentials.

          3) Authentication and SQL authorization:

          • Credentials are required, and only the DBO is allowed to drop the
            database.

          For startMaster=true, we have this:

          1) Authentication only:

          • Replication can be started by any user, but credentials are
            required.

          2) SQL authorization only:

          • Replication can be started by any user without providing
            credentials.

          3) Authentication and SQL authorization:

          • Credentials are required, and only the DBO is allowed to start
            replication.

          So it looks like database shutdown and drop=true follows the same
          pattern as startMaster=true, whereas system shutdown breaks that
          pattern.

          Also, the documentation for startMaster=true is a bit inaccurate since
          it implies that credentials are required if only SQL authorization is
          enabled, and that only the DBO can start replication, whereas that's
          only true if both authentication and SQL authorization are enabled.

          I propose this new wording for all replication attributes (I think it
          applies to all, but I've only tested startSlave=true and
          startMaster=true), and for drop=true:

          "If authentication is turned on, you must also specify this attribute
          in conjunction with the user=userName and password=userPassword
          attributes. If both authentication and SQL authorization are turned
          on, the user must be the database owner."

          For shutdown=true, we could use the same wording with the extra
          qualification that it only applies to shutdown of a single database.
          We would also need to mention that system shutdown requires
          user=userName/password=userPassword if both authentication and SQL
          authorization are enabled.

          Show
          Knut Anders Hatlen added a comment - Thanks, Dag. I had forgotten about that. It's actually a bit more complicated: 1) Authentication only: System shutdown can be performed by any user and without providing credentials. Database shutdown can be performed by any user, but credentials are required. 2) SQL authorization only: System shutdown can be performed by any user without providing credentials. Database shutdown can be performed by any user without providing credentials. 3) Authentication and SQL authorization: System shutdown requires credentials, but it can be performed by any user. Database shutdown requires credentials, and it can only be performed by the DBO. For drop=true, we have this: 1) Authentication only: Databases can be dropped by any user, but credentials are required. 2) SQL authorization only: Databases can be dropped by any user without providing credentials. 3) Authentication and SQL authorization: Credentials are required, and only the DBO is allowed to drop the database. For startMaster=true, we have this: 1) Authentication only: Replication can be started by any user, but credentials are required. 2) SQL authorization only: Replication can be started by any user without providing credentials. 3) Authentication and SQL authorization: Credentials are required, and only the DBO is allowed to start replication. So it looks like database shutdown and drop=true follows the same pattern as startMaster=true, whereas system shutdown breaks that pattern. Also, the documentation for startMaster=true is a bit inaccurate since it implies that credentials are required if only SQL authorization is enabled, and that only the DBO can start replication, whereas that's only true if both authentication and SQL authorization are enabled. I propose this new wording for all replication attributes (I think it applies to all, but I've only tested startSlave=true and startMaster=true), and for drop=true: "If authentication is turned on, you must also specify this attribute in conjunction with the user=userName and password=userPassword attributes. If both authentication and SQL authorization are turned on, the user must be the database owner." For shutdown=true, we could use the same wording with the extra qualification that it only applies to shutdown of a single database. We would also need to mention that system shutdown requires user=userName/password=userPassword if both authentication and SQL authorization are enabled.
          Hide
          Kim Haase added a comment -

          Thanks very much, Knut! I'll file a new issue for these changes.

          Show
          Kim Haase added a comment - Thanks very much, Knut! I'll file a new issue for these changes.
          Hide
          Dag H. Wanvik added a comment -

          You are right, Knut, been a while.. As for system shut down, we couldn't use the DBO requirement for that, since DBO is data base specific (in the general case). The work on system privileges was intended to protect system shutdown (among other operations), but that was work (DERBY-2901) not completed. +1 to the wording changes.

          Show
          Dag H. Wanvik added a comment - You are right, Knut, been a while.. As for system shut down, we couldn't use the DBO requirement for that, since DBO is data base specific (in the general case). The work on system privileges was intended to protect system shutdown (among other operations), but that was work ( DERBY-2901 ) not completed. +1 to the wording changes.
          Hide
          Kim Haase added a comment -

          The incorrect statement is gone from Latest Alpha Manuals; subsequent fix to DERBY-5212 makes this fix obsolete.

          Show
          Kim Haase added a comment - The incorrect statement is gone from Latest Alpha Manuals; subsequent fix to DERBY-5212 makes this fix obsolete.

            People

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

              Dates

              • Created:
                Updated:
                Resolved:

                Development