Q Why can PaperCut’s database become corrupted?
A full disk or any sort of disk corruption such as those caused by power outages or unexpected system shutdown/failures can corrupt the PaperCut database.
Q What are the symptoms of a corrupt PaperCut database?
There are a number of different symptoms of a database corruption. The symptoms displayed on a particular site will depend on the type of corruption occurring. Some examples include:
If you encounter any of the above errors, it indicates the internal database has been corrupted, and you should restore the database as described below.
Q How do I restore a PaperCut database if the database is corrupted?
You will need at least one good database export file from the backup directory
[app-path]\server\data\backups\. To restore the database follow these instructions:
Option 1 - Restore via your own backup software
If you have an off disk backup, simply:
- Stop the PaperCut Application Server service (Control Panel→Admin Tools→Services), or run the stop-server script in
[app-path]\server\bin\[platform] if running on Linux or Mac.
- Restore all files and folders located at:
Option 2 - Restore using one of PaperCut’s point-in-time exports
Logon to the PaperCut
Stop the PaperCut
Application Server service (Control Panel→Admin Tools→Services), or run the stop-server script in
if running on Linux or Mac.
As a backup, take a copy of the
Open a command prompt (cmd.exe). Please note that in some versions of Windows (notably Vista and 7) you will need to ensure this is an elevated command prompt with local administrator privileges. If you receive any errors or warnings relating to permissions or access denied, please close your command prompt and restart it as an elevated command prompt.
Change to the
cd “C:\Program Files\PaperCut NG\server\bin\win\”
Run the following command to re-initialize the database:
db-tools.exe init-db -f
7. Then restore your export into the database by doing the following (changing the export file name as appropriate)
db-tools.exe import-db “C:\Program Files\PaperCut NG\server\data\backups\export-2009–05–10T00–20–03.zip”
8. Once completed, restart the application server service.
Note: If during the restore process you receive an error stating that the database still exists, then run the import-db command with the -f option.
db-tools.exe import-db -f “C:\Program Files\PaperCut NG\server\data\backups\export-2009–05–10T00–20–03.zip”
Q My database was corrupt and I’ve restored from backup. How can I prevent this from occurring again?
First of all, it may be “just one of those things”. Stuff-happens with computers from time to time. e.g. random disk/memory issues. However any form of file corruption should trigger a few system administration tasks. The problem may indicate a system degradation and it would be good to catch this early (e.g. progressive disk failure). Take some time now to do some system checks such as a file system check and memory check.
Q What systems does PaperCut have in place to detect corruption?
Important data stored in PaperCut (configuration, print logs, user data, etc.) is stored in a relational database (RDMS). All databases supported by PaperCut including the default internal database (Apache Derby) are ACID compliant. One of the issues with databases is that data corruption is usually only detected when the data affected is actually fetched/read.
To ensure data integrity issues are detected early PaperCut uses a number of methods of proactive data monitoring. The main mechanism is a scheduled overnight weekly “data walk”. PaperCut’s point-in-time database export procedure reads all data in the RDMS and tests the referential integrity during this process. Any issues are immediately flagged and if configured, the system will email the administrator. PaperCut also actively monitors other system states relating to integrity such as operating system hard disk space. If low space is detected, again administrators are notified preempting the issue. This process has been in production use in PaperCut since 2006 and has proven very effective at early detection of data integrity issues. We have over 30,000 sites running PaperCut and very few data loss events have been reported. Any events that have occurred usually relate to hardware failure or human error outside the domain of software control.
keywords: corrupt, database, restore, derby error, database connection error