[jira] [Closed] (DERBY-5508) Improve backup/restore documentation visibility and content to encourage proper backups and restore procedures

> 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.1.0
>            Reporter: Kathey Marsden
>            Assignee: Kim Haase
>             Fix For: 10.8.2.3, 10.9.1.0
>
>         Attachments: DERBY-5508-2.diff, DERBY-5508-2.zip, DERBY-5508.diff, DERBY-5508.stat, DERBY-5508.zip
>
>
> 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