[ 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