[
https://issues.apache.org/jira/browse/DERBY-6845?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=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)
