You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Kim Haase (Commented) (JIRA)" <ji...@apache.org> on 2012/04/17 18:02:17 UTC
[jira] [Commented] (DERBY-5508) Improve backup/restore
documentation visibility and content to encourage proper backups and
restore procedures
[ 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