[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[ https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15578183#comment-15578183 ] Rick Hillegas commented on DERBY-6845: -- Hi Bryan, I think you're right that the section on derbyrun.jar needs to be updated as you described. Thanks! > Document the rawDBReader optional tool > -- > > Key: DERBY-6845 > URL: https://issues.apache.org/jira/browse/DERBY-6845 > Project: Derby > Issue Type: Improvement > Components: Documentation >Affects Versions: 10.13.1.0 >Reporter: Rick Hillegas >Assignee: Rick Hillegas > Fix For: 10.13.1.0 > > Attachments: derby-6845-01-aa-firstCut.diff, > derby-6845-01-aa-firstCut.tar, derby-6845-01-ab-moreExplanation.diff, > derby-6845-01-ab-moreExplanation.tar, derby-6845-01-ac-subheadings.diff, > derby-6845-01-ac-subheadings.tar > > > Document the optional tool added by DERBY-6136. -- This message was sent by Atlassian JIRA (v6.3.4#6332)
[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[
https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15574027#comment-15574027
]
Bryan Pendleton commented on DERBY-6845:
As I read our build.xml file:
{quote}
{quote}
the derbyrun.jar file indeed pulls both derbytools.jar and
derbyoptionaltools.jar into my classpath.
So maybe I just needed derbyrun.jar in my CLASSPATH to use the tool.
I think this indicates that this documentation is incorrect:
https://builds.apache.org/job/Derby-docs/lastSuccessfulBuild/artifact/trunk/out/adminguide/tadminappschangingyourclasspath.html
because it seemed to me to quite explicitly say that derbyrun.jar includes
**ONLY** derby.jar, derbynet.jar, and derbyclient.jar.
At any rate, I don't think any particular change to our docs is necessary at
this time, I'm
just rather obsessively following up my own comment from before :)
> Document the rawDBReader optional tool
> --
>
> Key: DERBY-6845
> URL: https://issues.apache.org/jira/browse/DERBY-6845
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
>Affects Versions: 10.13.1.0
>Reporter: Rick Hillegas
>Assignee: Rick Hillegas
> Fix For: 10.13.1.0
>
> Attachments: derby-6845-01-aa-firstCut.diff,
> derby-6845-01-aa-firstCut.tar, derby-6845-01-ab-moreExplanation.diff,
> derby-6845-01-ab-moreExplanation.tar, derby-6845-01-ac-subheadings.diff,
> derby-6845-01-ac-subheadings.tar
>
>
> Document the optional tool added by DERBY-6136.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[ https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15573483#comment-15573483 ] Rick Hillegas commented on DERBY-6845: -- Thanks for test-driving the tool, Bryan. Except for the second argument (which is a BOOLEAN), all of the arguments to syscs_util.syscs_register_tool are VARCHAR(32762) and therefore case-sensitive. The Reference Guide section on that procedure should probably say so. In addition, the Reference Guide section doesn't list several tools, including the rawDBReader tool. I have logged derby 6915 to track these defects. The rawDBReader code resides in a class called RawDBReader, which lives in derbyoptionaltools.jar and only in that jar. Maybe you were able to access the because your classpath contained derbyrun.jar and because of the classpath directives wired into derbyrun.jar? The material on rawDBReader in the Tools Guide does not describe a classpath which includes derbyrun.jar. > Document the rawDBReader optional tool > -- > > Key: DERBY-6845 > URL: https://issues.apache.org/jira/browse/DERBY-6845 > Project: Derby > Issue Type: Improvement > Components: Documentation >Affects Versions: 10.13.1.0 >Reporter: Rick Hillegas >Assignee: Rick Hillegas > Fix For: 10.13.1.0 > > Attachments: derby-6845-01-aa-firstCut.diff, > derby-6845-01-aa-firstCut.tar, derby-6845-01-ab-moreExplanation.diff, > derby-6845-01-ab-moreExplanation.tar, derby-6845-01-ac-subheadings.diff, > derby-6845-01-ac-subheadings.tar > > > Document the optional tool added by DERBY-6136. -- This message was sent by Atlassian JIRA (v6.3.4#6332)
[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[
https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15570589#comment-15570589
]
Bryan Pendleton commented on DERBY-6845:
The documentation says:
{quote}
Your classpath must contain derby.jar, derbytools.jar, and
derbyoptionaltools.jar.
{quote}
I successfully performed both the SYSCS_REGISTER_TOOL() invocation and the
invocation of the recovery.sql script with a classpath that was:
derbyrun.jar;derbytools.jar
Is this a bug in the documentation? A bug in my understanding of the behavior
of derbyrun.jar?
Somewhere in-between?
> Document the rawDBReader optional tool
> --
>
> Key: DERBY-6845
> URL: https://issues.apache.org/jira/browse/DERBY-6845
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
>Affects Versions: 10.13.1.0
>Reporter: Rick Hillegas
>Assignee: Rick Hillegas
> Fix For: 10.13.1.0
>
> Attachments: derby-6845-01-aa-firstCut.diff,
> derby-6845-01-aa-firstCut.tar, derby-6845-01-ab-moreExplanation.diff,
> derby-6845-01-ab-moreExplanation.tar, derby-6845-01-ac-subheadings.diff,
> derby-6845-01-ac-subheadings.tar
>
>
> Document the optional tool added by DERBY-6136.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[
https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15570485#comment-15570485
]
Bryan Pendleton commented on DERBY-6845:
I think an improvement to the documentation would be: to make it more
crystal-clear
that the first argument on the syscs_util.syscs_register_tool() call MUST be
'rawDBReader'. I was tired, and working fast, and entered 'rawDBreader',
and even though the system gave the (entirely correct) message:
{quote}
ERROR X0Y88: Unknown optional tool: 'rawDBreader'
{quote}
it still took me a frustrating 10 minutes to spot that tiny mistake.
> Document the rawDBReader optional tool
> --
>
> Key: DERBY-6845
> URL: https://issues.apache.org/jira/browse/DERBY-6845
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
>Affects Versions: 10.13.1.0
>Reporter: Rick Hillegas
>Assignee: Rick Hillegas
> Fix For: 10.13.1.0
>
> Attachments: derby-6845-01-aa-firstCut.diff,
> derby-6845-01-aa-firstCut.tar, derby-6845-01-ab-moreExplanation.diff,
> derby-6845-01-ab-moreExplanation.tar, derby-6845-01-ac-subheadings.diff,
> derby-6845-01-ac-subheadings.tar
>
>
> Document the optional tool added by DERBY-6136.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[ https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15043373#comment-15043373 ] ASF subversion and git services commented on DERBY-6845: Commit 1718103 from [~rhillegas] in branch 'docs/trunk' [ https://svn.apache.org/r1718103 ] DERBY-6845: Document the rawDBReader optional tool; commit derby-6845-01-ac-subheadings.diff. > Document the rawDBReader optional tool > -- > > Key: DERBY-6845 > URL: https://issues.apache.org/jira/browse/DERBY-6845 > Project: Derby > Issue Type: Improvement > Components: Documentation >Affects Versions: 10.13.0.0 >Reporter: Rick Hillegas >Assignee: Rick Hillegas > Attachments: derby-6845-01-aa-firstCut.diff, > derby-6845-01-aa-firstCut.tar, derby-6845-01-ab-moreExplanation.diff, > derby-6845-01-ab-moreExplanation.tar, derby-6845-01-ac-subheadings.diff, > derby-6845-01-ac-subheadings.tar > > > Document the optional tool added by DERBY-6136. -- This message was sent by Atlassian JIRA (v6.3.4#6332)
[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[ https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15042620#comment-15042620 ] Bryan Pendleton commented on DERBY-6845: The new documentation looks very good to me. I think you could perhaps structure it a bit more with some sub-headings so that it's not just one long section. But even without that, it reads clearly and and sets the process out in a very straightforward and clear manner. Regarding this section: To run the rawDBReader tool, you must be signed on to the machine where the corrupt database resides and your classpath must contain derby.jar and derbyoptionaltools.jar. Is it true that "healthydb" must also be on the same machine as the corruptDB? (That is, everything is accessed using the embedded engine, and is local to the machine you are on?) Overall, I think this is excellent, particularly for the first release of the tool. If we get further feedback from people who find themselves using the tool, we can improve the docs some more in the future. > Document the rawDBReader optional tool > -- > > Key: DERBY-6845 > URL: https://issues.apache.org/jira/browse/DERBY-6845 > Project: Derby > Issue Type: Improvement > Components: Documentation >Affects Versions: 10.13.0.0 >Reporter: Rick Hillegas >Assignee: Rick Hillegas > Attachments: derby-6845-01-aa-firstCut.diff, > derby-6845-01-aa-firstCut.tar, derby-6845-01-ab-moreExplanation.diff, > derby-6845-01-ab-moreExplanation.tar > > > Document the optional tool added by DERBY-6136. -- This message was sent by Atlassian JIRA (v6.3.4#6332)
[jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
[ https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel=15039555#comment-15039555 ] Bryan Pendleton commented on DERBY-6845: Hi Rick, Thanks for putting together the draft documentation. Here's some feedback. This is an interesting tool to document, because the premise of the tool is that a Very Bad Thing has happened, and the user is in a Serious Panic. So we want to say some very calming words, and set them up for success, because their emotional state is likely to be poor when they are reading this page. I think you have done a very good job at this, but I think we can make the documentation still further calming and step-by-step. I expect that after you read my feedback you'll want to take another swing at this, and maybe we can toss about some ideas. Wherever we end up, thanks again for putting the tool together, it is VERY nice to have it on hand for when lightning strikes. thanks, bryan 1) I think the word "siphon" might be hard for many readers, particularly non-English-speakers. Perhaps something like "extract" or "unload" or "recover" or "copy" or "retrieve"? 2) I read 'corrupt, unbootable' as "corrupt AND unbootable"; I assume that rawDBReader can be used on "corrupt yet bootable" databases as well, so perhaps we should be explicit and say "corrupt or unbootable", or "corrupt databases, even if they are unbootable"? Or, if the tool is really designed only for unbootable databases, then maybe just remove the "corrupt," since an unbootable database is clearly corrupt. 3) I'd remove ", as with any database engine,", because who cares about anybody else :) 4) Perhaps change "This technique is not guaranteed" to "The rawDBReader tool is not guaranteed". 5) I'd remove "Strictly speaking," 6) Perhaps change For the remainder of this section, we will talk about two databases: to When running the rawDBReader tool, you will be working with two databases: corruptDB - This is the unbootable database whose data you are trying to salvage. healthyDB - This is a new database which you create in order to hold the retrieved data. The rawDBReader tool works by copying all your data from the unbootable database into a totally separate database. Each table in the corruptDB will be copied to a table with the same table name and column names in healthyDB, but the table will be in a separate schema so you can tell which is which. 7) Perhaps change the part where you say: To load the rawDBReader tool to something like: Using the rawDBReader tool is a three-step process: 1) You call SYSCS_REGISTER_TOOL with the correct arguments, which will prepare the healthyDB to accept any data from the corruptDB, and will also generate a text file containing a series of commands. This text file is called the 'recovery script'. 2) You then run the recovery script to retrieve all your data from the corruptDB into the healthyDB 3) After this is done, you unload the tool by making another SYSCS_REGISTER_TOOL call. These three steps are described in more detail below. 8) In both your examples you use "CONTROL_" as the name of your control schema, but then your example recovery script uses 'S1'. That was confusing. Can that be made more clear? 9) All your examples are with embedded syntax. Does the tool work with a client-server configuration? If so, we should probably document what adjustments are necessary; if not, we should simply say something like: To run the rawDBReader tool, you must be signed on to the machine where the corruptDB resides and you must have the derby.jar and derbytools.jar files in your CLASSPATH. > Document the rawDBReader optional tool > -- > > Key: DERBY-6845 > URL: https://issues.apache.org/jira/browse/DERBY-6845 > Project: Derby > Issue Type: Improvement > Components: Documentation >Affects Versions: 10.13.0.0 >Reporter: Rick Hillegas >Assignee: Rick Hillegas > Attachments: derby-6845-01-aa-firstCut.diff, > derby-6845-01-aa-firstCut.tar > > > Document the optional tool added by DERBY-6136. -- This message was sent by Atlassian JIRA (v6.3.4#6332)
