db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Bryan Pendleton (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (DERBY-6845) Document the rawDBReader optional tool
Date Fri, 04 Dec 2015 01:34:10 GMT

    [ 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.



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:


        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

        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

        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:
>            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

View raw message