Derby
  1. Derby
  2. DERBY-2042

Provide documentation for new RENAME COLUMN statement

    Details

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

      Description

      DERBY-1490 proposes to add a new RENAME COLUMN statement. Assuming that such a statement is added, we need to update the documentation to describe this new statement. DERBY-1490 describes the behavior of the statement in detail; this issue is just to track the documentation, which I intend to address separately after the DERBY-1490 changes are committed.

      1. rrefsqljrenamecolumnstatement.html
        4 kB
        Bryan Pendleton
      2. rrefsqljrenamecolumnstatement.html
        5 kB
        Bryan Pendleton
      3. rrefsqljrenamecolumnstatement.html
        6 kB
        Bryan Pendleton
      4. renameColumnDoc_v3_changedSyntaxRefs.diff
        5 kB
        Bryan Pendleton
      5. renameColumnDoc_v2.diff
        5 kB
        Bryan Pendleton
      6. renameColumnDoc_v1.diff
        4 kB
        Bryan Pendleton

        Issue Links

          Activity

          Bryan Pendleton created issue -
          Bryan Pendleton made changes -
          Field Original Value New Value
          Link This issue depends on DERBY-1490 [ DERBY-1490 ]
          Bryan Pendleton made changes -
          Assignee Bryan Pendleton [ bryanpendleton ]
          Hide
          Bryan Pendleton added a comment -

          Attached is a change proposal for the docs to add a new page to the reference guide for the RENAME COLUMN statement. I have also attached the formatted HTML page, as that is probably easier for reviewers to read.

          Please review and provide your feedback. Thanks!

          Show
          Bryan Pendleton added a comment - Attached is a change proposal for the docs to add a new page to the reference guide for the RENAME COLUMN statement. I have also attached the formatted HTML page, as that is probably easier for reviewers to read. Please review and provide your feedback. Thanks!
          Bryan Pendleton made changes -
          Attachment rrefsqljrenamecolumnstatement.html [ 12344358 ]
          Attachment renameColumnDoc_v1.diff [ 12344357 ]
          Bryan Pendleton made changes -
          Derby Info [Patch Available]
          Hide
          Knut Anders Hatlen added a comment -

          Hi Bryan,
          I had a look at the HTML page. I haven't tested how RENAME COLUMN actually works, nor have I looked at the code, so please forgive my ignorance. Here are my comments:

          1. The documentation says that you can "rename an existing column in an existing table in any schema", but it doesn't say how you can specify the schema. The syntax only says table-Name.column, not [schema-Name.]table-Name.column. Or is the current schema always used?

          2. It is not quite clear to me what function this statement has: "RENAME COLUMN EMPLOYEE.MANAGER TO SUPERVISOR". Is it an example of how to use RENAME COLUMN, or is it an example of a statement that causes the error described in the preceding paragraph?

          3. In the paragraph with "Note that you can combine these tools to...", the first sentence says "you" and the second says "I". I think it would be better to use "you" in both sentences. I think I also would have dropped "as follows".

          4. "to new datatype" should have "data type" in two words, and perhaps "a" or "the" before "new"?

          5. Is the following statement correct? "If there is an index defined on the column, the column can be renamed." Should it have been "cannot"?

          Show
          Knut Anders Hatlen added a comment - Hi Bryan, I had a look at the HTML page. I haven't tested how RENAME COLUMN actually works, nor have I looked at the code, so please forgive my ignorance. Here are my comments: 1. The documentation says that you can "rename an existing column in an existing table in any schema", but it doesn't say how you can specify the schema. The syntax only says table-Name.column, not [schema-Name.] table-Name.column. Or is the current schema always used? 2. It is not quite clear to me what function this statement has: "RENAME COLUMN EMPLOYEE.MANAGER TO SUPERVISOR". Is it an example of how to use RENAME COLUMN, or is it an example of a statement that causes the error described in the preceding paragraph? 3. In the paragraph with "Note that you can combine these tools to...", the first sentence says "you" and the second says "I". I think it would be better to use "you" in both sentences. I think I also would have dropped "as follows". 4. "to new datatype" should have "data type" in two words, and perhaps "a" or "the" before "new"? 5. Is the following statement correct? "If there is an index defined on the column, the column can be renamed." Should it have been "cannot"?
          Hide
          Knut Anders Hatlen added a comment -

          In the example that shows how to change the type of a column, is it really necessary to rename c1 to c1_oldtype before it is dropped? Couldn't the example be simplified to this:

          • ALTER TABLE t ADD COLUMN c1_newtype NEWTYPE;
          • UPDATE t SET c1_newtype = c1;
          • ALTER TABLE t DROP COLUMN c1;
          • ALTER TABLE t RENAME COLUMN c1_newtype to c1;

          ?

          Also, would it be better if the example were in a code block rather than in a list?

          Show
          Knut Anders Hatlen added a comment - In the example that shows how to change the type of a column, is it really necessary to rename c1 to c1_oldtype before it is dropped? Couldn't the example be simplified to this: ALTER TABLE t ADD COLUMN c1_newtype NEWTYPE; UPDATE t SET c1_newtype = c1; ALTER TABLE t DROP COLUMN c1; ALTER TABLE t RENAME COLUMN c1_newtype to c1; ? Also, would it be better if the example were in a code block rather than in a list?
          Hide
          Laura Stewart added a comment -

          Hi Bryan -

          A couple of comments:

          You have a section entitled "Statement dependency system".
          This seems like an oddly worded section.
          I think that it would be best if the content of the section was moved before the syntax.

          You state "If there is an index defined on the column, the column can be renamed."
          Does this mean that you can only rename a column that has an index?
          If yes then this is a "restriction" to the RENAME COLUMN statement.
          If any column, even those with indexes can be renamed, then you might just want to state that.

          The next item "The RENAME COLUMN statement is not allowed if there are any open cursors that reference the column that is being altered."
          is definitely a restriction. We typically don't add "Restrictions" sections to reference topics. But it would be good to use a note.
          The tagging is:
          <note="restriction">You cannot use the RENAME COLUMN statement if there are open cursors that reference the column that you want to rename."</note>

          You can see an example of using the note tag on the new "Writing Guidelines" page that I added to the Derby Documentation site:
          http://db.apache.org/derby/manuals/guidelines.html#Tagging+examples

          Also, it would be helpful if you created a section for the examples entitled "Examples"
          See the GRANT statement in the Reference Guide for an example
          http://db.apache.org/derby/docs/dev/ref/rrefsqljgrant.html

          Finally, I asked on the list a few months ago about using the semi-colon at the end of SQL statements.
          The Derby community indicated that they did NOT want to use them.
          See this thread:
          http://www.nabble.com/Documentation-Style-Issue---semi-colon-at-the-end-of-SQL-statement-examples-tf2141831.html#a5912069

          Show
          Laura Stewart added a comment - Hi Bryan - A couple of comments: You have a section entitled "Statement dependency system". This seems like an oddly worded section. I think that it would be best if the content of the section was moved before the syntax. You state "If there is an index defined on the column, the column can be renamed." Does this mean that you can only rename a column that has an index? If yes then this is a "restriction" to the RENAME COLUMN statement. If any column, even those with indexes can be renamed, then you might just want to state that. The next item "The RENAME COLUMN statement is not allowed if there are any open cursors that reference the column that is being altered." is definitely a restriction. We typically don't add "Restrictions" sections to reference topics. But it would be good to use a note. The tagging is: <note="restriction">You cannot use the RENAME COLUMN statement if there are open cursors that reference the column that you want to rename."</note> You can see an example of using the note tag on the new "Writing Guidelines" page that I added to the Derby Documentation site: http://db.apache.org/derby/manuals/guidelines.html#Tagging+examples Also, it would be helpful if you created a section for the examples entitled "Examples" See the GRANT statement in the Reference Guide for an example http://db.apache.org/derby/docs/dev/ref/rrefsqljgrant.html Finally, I asked on the list a few months ago about using the semi-colon at the end of SQL statements. The Derby community indicated that they did NOT want to use them. See this thread: http://www.nabble.com/Documentation-Style-Issue---semi-colon-at-the-end-of-SQL-statement-examples-tf2141831.html#a5912069
          Hide
          Bryan Pendleton added a comment -

          Thanks for the feedback!

          I was sort of mimicing the existing pages for RENAME TABLE and RENAME INDEX, but I think your points are very good and I think it is better to make this page clear than to worry about whether it is consistent with those other pages.

          I will re-submit this patch later, taking into account these comments, which I think will improve the page considerably.

          Show
          Bryan Pendleton added a comment - Thanks for the feedback! I was sort of mimicing the existing pages for RENAME TABLE and RENAME INDEX, but I think your points are very good and I think it is better to make this page clear than to worry about whether it is consistent with those other pages. I will re-submit this patch later, taking into account these comments, which I think will improve the page considerably.
          Bryan Pendleton made changes -
          Derby Info [Patch Available]
          Hide
          Laura Stewart added a comment -

          I understand completely. Several of us (Kim Haase and myself) are trying to update the documentation to be more consistent.
          It is best if you model your topic after GRANT or REVOKE which were added in 10.2.1.6. They have the most current "look and feel" that we are going for.

          All in all, you did a good job

          Show
          Laura Stewart added a comment - I understand completely. Several of us (Kim Haase and myself) are trying to update the documentation to be more consistent. It is best if you model your topic after GRANT or REVOKE which were added in 10.2.1.6. They have the most current "look and feel" that we are going for. All in all, you did a good job
          Hide
          Bryan Pendleton added a comment -

          I took another stab at the reference guide page, and attempted
          to incorporate the various feedback.

          Attached is renameColumnDoc_v2.diff, and an updated
          copy of the HTML page that results from the build.

          Please let me know your comments on the revised page.

          Show
          Bryan Pendleton added a comment - I took another stab at the reference guide page, and attempted to incorporate the various feedback. Attached is renameColumnDoc_v2.diff, and an updated copy of the HTML page that results from the build. Please let me know your comments on the revised page.
          Bryan Pendleton made changes -
          Attachment renameColumnDoc_v2.diff [ 12344526 ]
          Attachment rrefsqljrenamecolumnstatement.html [ 12344527 ]
          Bryan Pendleton made changes -
          Derby Info [Patch Available]
          Hide
          Knut Anders Hatlen added a comment -

          Thanks Bryan, the changes look great!

          One last comment. I looked at how the page for CREATE INDEX defined the syntax. It doesn't mention schema name in the syntax description, but table-Name is a hyperlink to a page which defines table-Name as [ schemaName. ] SQL92Identifier. Also, I started wondering whether it is correct to use "new-Column-Name" in the syntax. Perhaps it is more semantics than syntax.

          I think we could write the syntax this way (with hyperlinks to the definitions of table-Name and Simple-column-Name):

          RENAME COLUMN table-Name.Simple-column-Name TO Simple-column-Name

          And a final nit: In the text that explains the examples, the identifiers "manager", "employee" and "supervisor" are written in plain text with no quotation marks, but "c1" and "t" are written in double quotes. Perhaps the DITA experts know a markup tag which could be used to consistently mark identifiers?

          Show
          Knut Anders Hatlen added a comment - Thanks Bryan, the changes look great! One last comment. I looked at how the page for CREATE INDEX defined the syntax. It doesn't mention schema name in the syntax description, but table-Name is a hyperlink to a page which defines table-Name as [ schemaName. ] SQL92Identifier. Also, I started wondering whether it is correct to use "new-Column-Name" in the syntax. Perhaps it is more semantics than syntax. I think we could write the syntax this way (with hyperlinks to the definitions of table-Name and Simple-column-Name): RENAME COLUMN table-Name.Simple-column-Name TO Simple-column-Name And a final nit: In the text that explains the examples, the identifiers "manager", "employee" and "supervisor" are written in plain text with no quotation marks, but "c1" and "t" are written in double quotes. Perhaps the DITA experts know a markup tag which could be used to consistently mark identifiers?
          Hide
          Bryan Pendleton added a comment -

          Attached is renameColumnDoc_v3_changedSyntaxRefs.diff, an updated patch proposal which incorporates Knut Anders's suggestions:

          1) The text describing the examples uses italics to refer to the table and
          column names in the examples, rather than putting them in quotation
          marks, which I agree looks superior.

          2) The syntax block now refers to the table-name and simple-column-name
          topics, which don't appear to be a perfect match, but are pretty close to it.
          As Knut Anders observes, this should help to describe the various combinations
          of schema name, table name, and column name more rigorously.

          Please have a look. I've attached the HTML output file as well, for easier review.

          Show
          Bryan Pendleton added a comment - Attached is renameColumnDoc_v3_changedSyntaxRefs.diff, an updated patch proposal which incorporates Knut Anders's suggestions: 1) The text describing the examples uses italics to refer to the table and column names in the examples, rather than putting them in quotation marks, which I agree looks superior. 2) The syntax block now refers to the table-name and simple-column-name topics, which don't appear to be a perfect match, but are pretty close to it. As Knut Anders observes, this should help to describe the various combinations of schema name, table name, and column name more rigorously. Please have a look. I've attached the HTML output file as well, for easier review.
          Bryan Pendleton made changes -
          Attachment renameColumnDoc_v3_changedSyntaxRefs.diff [ 12344627 ]
          Attachment rrefsqljrenamecolumnstatement.html [ 12344628 ]
          Hide
          Knut Anders Hatlen added a comment -

          Thanks Bryan, I think the latest version looks good.

          Show
          Knut Anders Hatlen added a comment - Thanks Bryan, I think the latest version looks good.
          Hide
          Bryan Pendleton added a comment -

          Committed the new doc page to subversion as revision 472990. I'll mark this issue closed once I confirm that the new page is accessible from the apache.org web site.

          Show
          Bryan Pendleton added a comment - Committed the new doc page to subversion as revision 472990. I'll mark this issue closed once I confirm that the new page is accessible from the apache.org web site.
          Bryan Pendleton made changes -
          Fix Version/s 10.3.0.0 [ 12310800 ]
          Resolution Fixed [ 1 ]
          Derby Info [Patch Available]
          Status Open [ 1 ] Resolved [ 5 ]
          Hide
          Bryan Pendleton added a comment -

          Verified that doc is visible on the main apache site.

          Show
          Bryan Pendleton added a comment - Verified that doc is visible on the main apache site.
          Bryan Pendleton made changes -
          Status Resolved [ 5 ] Closed [ 6 ]
          Gavin made changes -
          Link This issue depends on DERBY-1490 [ DERBY-1490 ]
          Gavin made changes -
          Link This issue depends upon DERBY-1490 [ DERBY-1490 ]
          Gavin made changes -
          Workflow jira [ 12388506 ] Default workflow, editable Closed status [ 12798211 ]

            People

            • Assignee:
              Bryan Pendleton
              Reporter:
              Bryan Pendleton
            • Votes:
              0 Vote for this issue
              Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved:

                Development