Resolving PaperCut NG/MF performance issues by maintaining its internal database

By default, PaperCut NG/MF uses an internal Apache Derby database. For many organizations, this internal database is sufficient. However, larger organizations might outgrow it or need an external relational database management system (RDBMS) from the start. However, moving to an external database isn’t always a simple decision. Budget constraints might prevent purchasing an external database when performance issues first appear. Other limitations can include a lack of server capacity or the in-house expertise to manage an RDBMS, since not all organizations have a database administrator (DBA). Some organizations have used PaperCut NG/MF for over a decade. Over this time, the database grows as it stores job records (print, copy, scan, fax) and transaction logs. While disk space is generally not an issue, the total amount of data can eventually exceed the performance limits of the internal Apache Derby database. You might notice that running a report takes much longer than it used to, or the Job Log page in the Admin web interface becomes unresponsive when you apply a filter. In severe cases, these tasks can cause the Application Server to stop responding, requiring a service restart to restore functionality. This page provides various methods for maintaining your system’s performance. Optimize the internal database If you use the internal database and experience these performance issues, first try optimizing the database . To check your database type: Log in to the Admin web interface. Go to the About tab. In the System Info section, look for the Database entry. If it says ‘Internal’, this guide applies to your deployment. Increase server resources If optimizing the database doesn’t resolve the performance issues, investigate increasing the resources available to the Application Server. Virtual Machine (VM): If your server is a VM, you can increase its allocated vCPUs and/or memory. As per our recommendations for virtualized environments , ensure these resources are dedicated. Physical Server: If you use a physical server, your options are more limited. You might consider migrating the Application Server to a more powerful machine in your environment. Our Server Sizing Guide can help you determine how much to increase your server’s resources. Upsize to a free external database Organizations that move to an external database almost always see these performance issues resolved. If budget or hardware limitations are a concern, there are free alternatives. Microsoft SQL Server Express, PostgreSQL, and MySQL Community Edition are free database solutions that can be used in production environments. See the System Requirements page , Database Servers section. Note Free solutions often have restrictions or lack features found in their paid versions. Research these limitations before choosing a free database for your PaperCut NG/MF deployment. For smaller organizations, it can be appropriate to install the database on the same server as the Application Server (colocation). Before doing this, check your server’s resource usage during your busiest printing periods. On Windows servers, you can use the Performance tab in Task Manager. If the average CPU and memory usage are consistently below 50% during peak times, it might be safe to deploy the database on the same machine. Clear out older records Performance issues with the internal database can mean that your organization has outgrown its capacity. Our System Requirements guide suggests that the internal database might be insufficient for sites with more than 5,000 users or 500,000 print logs. You can check your Print log count and Account transaction count in the Admin web interface under the About tab > Database Size Statistics section. If your performance issues are slow reports or unresponsive log filtering, the cause might be the large volume of historical data. If other solutions are not viable, you can archive old records and then purge them from the live database to improve performance. How to purge old data from the internal database This manual process incrementally removes the oldest records from your internal database in several passes to avoid overwhelming the system. Before you begin Before purging the data, you need to determine how many days’ worth of data to initially purge, schedule a maintenance window, and perform backups. Calculate the age of records to delete. Check the Since date in the Admin web interface under the Dashboard tab, in the Environmental Impact section. Use this to determine a starting number of days for the purge. For example, if today is June 24, 2025, and your Since date is Dec 11, 2014: 2025 - 2014 = 11 years (11 - 1) * 365 = 3650 days Your starting value is 3650. This will purge records older than 10 years. Warning Do not use a value of 0. This will delete all historical records from your database. Schedule a maintenance window when a PaperCut NG/MF outage will not cause disruption. Note that in some cases purging operations can take hours. Perform a full offline backup of your PaperCut NG/MF database. This backup serves as your archive of old data. Store a copy in a safe, off-site location that is also backed up. If possible, as an extra precaution, create a secondary backup (for example, a filesystem backup or a VM snapshot). You can use this backup to restore your system if you encounter any issues. Incrementally purge old data from the internal database Follow these steps to incrementally purge the old data until system performance improves. Stop the PaperCut Application Server service. Open a Command Prompt (Windows) or Terminal (macOS/Linux) session with administrator privileges. Navigate to the db-tools directory. For example: Windows: cd "C:\Program Files\PaperCut [NG/MF]\server\bin\win" macOS: sudo su - papercut; cd "/Applications/PaperCut [NG/MF]/server/bin/mac" Linux: sudo su - papercut; cd ~/server/bin/linux-x64 Run the db-tools command to purge historical log data using the number of days you calculated earlier: db-tools delete-old-logs [number-of-days] For example: db-tools delete-old-logs 3650 Warning This operation can take a long time to complete, potentially hours. Performing multiple incremental purges keeps the duration of each run to a minimum. Restart the PaperCut Application Server service. Test to see if the performance issue is resolved (for example, run a report that was previously slow). If the issue persists, repeat steps 1 – 6. Subtract 365 from your previous number of days. For example, the next value after 3650 would be 3285 (purging records older than 9 years). Warning If you see no improvement after clearing records older than 3 years (1095 days), stop the process. Consider restoring from your backup and initiating a technical support request. Accessing your deleted internal/external database data After purging records, there are ways you can access your historical data, if required. This is useful if you need to access historical audit or application logging, or run reports on removed data. Option 1: Produce archival reports before purging If your system can still run reports (even if slowly), generate any reports you might need in the future before you purge the data. For example, use the Ad-hoc reporting option to generate yearly summaries for each year of data you intend to remove. Option 2: Restore an archival backup to a temporary server If you need to access purged data for auditing or other purposes, you can restore your archival backup to a temporary PaperCut NG/MF installation. Warning: Network disconnection required Before you proceed, you must disable all network connectivity on the machine used for the temporary installation. Otherwise, restoring your production database backup on a connected machine could disrupt your production server’s normal operation. Additionally, for PaperCut NG/MF 24.0 and later, the Application Server attempts to contact the Global Entitlements Service to register your license, which could interfere with your production server's license entitlements. Forcing the temporary machine offline prevents these problems. Download the latest installer of PaperCut NG/MF: Log in to your production Admin web interface. Go to the About tab and click Check for updates. Find a spare laptop or workstation. Copy the installer and your archival database backup file to the spare machine. Confirm the machine is completely disconnected from the network and internet. Run the installer on the spare machine to deploy a temporary Application Server. Complete the setup wizard to set a new password for the admin account. Other settings are not important. After installation, import your archival database backup into the temporary server. Log in to the temporary server’s Admin web interface at http://localhost:9191/admin using the password you set in step 5 above. You can now access all your historical data and run any reports you need. Before you reconnect the spare machine to the network, uninstall the temporary PaperCut NG/MF Application Server .