[
https://issues.apache.org/jira/browse/DERBY-5508?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13255677#comment-13255677
]
Kim Haase commented on DERBY-5508:
----------------------------------
Here are some initial thoughts about what work is needed for this issue.
Comments are welcome -- there are several items I'm particularly unsure about.
In the meantime, I'll get to work.
The topics that need work in order to help people back up databases properly
include the following (there may be more).
Admin Guide:
The material here is focused on the tasks alone. The introductory topic,
"Backing up and restoring databases" (cadminhubbkup98797.dita), should be
enhanced with enough conceptual information to help head off the problems
people might encounter. The two online backup topics should insert the
instruction to run SYSCS_UTIL.SYSCS_CHECK_TABLE before backing up. Similarly,
the "Checking database consistency" topic (cadminconsist01.dita) should mention
that the function should be run before backups.
It seems odd that the backup procedure needed to make roll-forward recovery
possible is not actually mentioned until the "Roll-forward recovery" topic
(cadminrollforward.dita). In fact, the topic "Using the backup procedure to
perform an online backup" (cadminhubbkup01.dita) mentions only one of the four
backup system procedures. Seems as if it should describe all four and when each
should be used. I'm not sure under what circumstances the NOWAIT versions
should be used, actually -- the Reference Manual topics don't say.
Reference Manual:
The "SYSCS_UTIL.SYSCS_CHECK_TABLE system function" topic should include a
mention that it should be run before backups, and a reference to the Admin
Guide should be added.
All the material on the SYSCS_UTIL.SYSCS_BACKUP_DATABASE procedures, the
SYSCS_UTIL.SYSCS_FREEZE_DATABASE and SYSCS_UTIL.SYSCS_UNFREEZE_DATABASE
procedures should cross-reference the Admin Guide.
The "restoreFrom=path attribute" topic (rrefrestorefrom.dita) already refers to
the Admin Guide. However, it implies that it is not possible to overwrite a
database when you do a restore (as in item 4 in your problem list), at least if
you use this attribute. Do the problems result from operating system restores
rather than those that use this attribute? This may also affect the other
attribute topics: "createFrom=path attribute" (rrefcreatefrom.dita),
"rollForwardRecoveryFrom=path attribute" (rrefrollforward.dita).
Getting Started:
There's no obvious place to insert specific pointers about backing up
databases, since the information in this guide is generally more basic than
that.
The "Product documentation for Derby" topic already mentions backups among the
Admin Guide tasks.
The "What next with Derby?" topic at the end of the tutorial could use some
major rearrangement and rewriting, actually. The Wiki page it most prominently
points to seems seriously out of date and should probably not be referenced, at
least not prominently -- instead the material at the end (paragraph and bullet
list) should be moved up to replace it. Also, the first place pointed to should
be the rest of the Derby documentation -- maybe a pointer back to the "Product
documentation for Derby" topic.
The "Quick start guide for experienced JDBC users" topic should also add a
paragraph pointing to the product documentation topic.
Developer's Guide:
There are existing pointers in "Preparing to upgrade" (tdevpreupgrade.dita),
"Creating, dropping, and backing up databases" (cdevdvlp42173.dita), and "Using
in-memory databases" (cdevdvlpinmemdb.dita).
The following topics could use a pointer to the Admin Guide where backups are
mentioned: "Upgrading an old database to use SQL standard authorization"
(cdevcsecuresqlauthupgrade.dita), "Encrypting an existing unencrypted database"
(tdevcsecureunencrypteddb.dita), "Encrypting databases with a new external
encryption key" (tdevcsecurenewextkey.dita), "Encrypting databases with a new
boot password" (tdevcsecurenewbootpw.dita).
> Improve backup/restore documentation visibility and content to encourage
> proper backups and restore procedures
> --------------------------------------------------------------------------------------------------------------
>
> Key: DERBY-5508
> URL: https://issues.apache.org/jira/browse/DERBY-5508
> Project: Derby
> Issue Type: Improvement
> Components: Documentation
> Affects Versions: 10.8.2.2, 10.9.0.0
> Reporter: Kathey Marsden
> Assignee: Kim Haase
>
> In a very large percentage of cases where users need to restore their
> backup, I have found that they don't have a usable backup to restore. It is
> often difficult to determine the root cause, so I am not sure of all of
> these, but my experience and suspicions are:
> 1) They relied on a operating system backup while the database was not
> shutdown or frozen.
> 2) They unknowingly backed up a corrupt database over their good backup
> because there was corruption that was not readily apparent at the time of
> the backup.
> 3) They relied on incremental backups (even when the database was shutdown)
> that did not properly track deletes.
> 4) They restored to an existing database directory without removing the old
> one first.
> 5) They didn't backup because the Derby backup was not included in the
> embedding application''s backup procedure.
> 6) The embedding application's did have a backup/restore procedure but it
> made one of the mistakes above.
> It would be good to think about our backup and restore documentation to make
> it more visible to users and developers and include tips for good backup
> procedures. Two things I can think of that might help are.
> 1) Encourage SYSCS_UTIL.SYSCS_CHECK_TABLE on all the tables of the database
> before backing up to help flag existing corruption before potential existing
> issues before overwriting a backup.
> 2) Put pointers in the Getting Started Guide and the Developers guide to the
> backup instructions in the Administration manual.
> I am sure others have ideas on how to improve the doc. Kim suggested I log
> this issue and track the various ideas so she can document them for the next
> release.
> The relevant doc references are:
> http://db.apache.org/derby/docs/10.8/adminguide/cadminbckupdb.html
> http://db.apache.org/derby/docs/10.8/adminguide/radminconsist24642.html
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators:
https://issues.apache.org/jira/secure/ContactAdministrators!default.jspa
For more information on JIRA, see: http://www.atlassian.com/software/jira
