Upsize to an external database (RDBMS)

By default, PaperCut NG/MF uses an internal database product known as Apache Derby. You might, however, consider running PaperCut NG/MF on an external RDBMS if your organization:

has existing database infrastructure and wants to consolidate all applications on the same database platform.
has an existing database maintenance and backup procedure and wants PaperCut NG/MF to take advantage of this
uses 3rd party reporting and analysis tools (like Crystal Reports or Microsoft Access) to view and analyze the PaperCut NG/MF database
is very large and requires the performance benefits of a dedicated RDBMS. This also allows the database to reside on a separate server to PaperCut NG/MF, which improves the system scalability.

The high-level steps to upsize the database are:

Stop the PaperCut NG/MF Application Server
Perform a backup of the existing data
Create a new database in the external RDBMS
Configure the database
Change the PaperCut NG/MF connection details
Initialize the new database
Load the data into the new database
Restart the application

Step 1: Stop the PaperCut NG/MF Application Server

Stop the Application Server. This allows you to back up the data, guaranteeing that all data is saved and ready to load into the new database.

For more information, see Stop and start the Application Server .

Step 2: Perform a backup of the existing data

Perform a backup of the database. This data is loaded into the application in a later step. For more information, see Manage system backups .

To back up the database:

On the Application Server, open a command prompt. (If you see ‘Access Denied’ errors, run the command prompt as an Administrator).
On Linux or Mac, use su or equivalent to become the identity of papercut. e.g.
Mac: sudo su - papercut
Linux: su - papercut
Change (cd) to the server binaries directory. e.g.
Windows: cd "C:\Program Files\PaperCut NG/MF\server\bin\win"
Mac: cd “/Applications/PaperCut NG/MF/server/bin/mac”
Linux: cd ~papercut/server/bin/linux-*
Run the following command:
db-tools export-db

The output of the above command shows the name of the backup file.
Take note of the backup file name because it is required in a later step.

Step 3: Create a new database in the external RDBMS

This step differs depending on the external database you are using. It is assumed that the administrator knows how to create a new database. The following steps must be performed regardless of the chosen database:

Create a new empty database for dedicated use by PaperCut NG/MF. When creating the database, make sure you select the correct character encoding for your language.

Create a new database user (and password) for PaperCut NG/MF to use to connect to the database.
Assign the appropriate permissions to the new user to give them full access to the new database (for example, permission to create/drop tables, and select/insert/update/delete in all tables).

Step 4: Configure the database

After you have created you database, you must configure it for PaperCut NG/MF. For more information, see:

Step 5: Change the PaperCut NG/MF connection details

This section walks through the connection settings needed for the PaperCut NG/MF Application Server to connect to your external database—including authentication, connection strings, and any database driver requirements.

On the Application Server, open the server config file in a text editor (for example, Notepad):
[app-path]/server/server.properties
(New installations only) Comment out the line:
database.type=Internal by adding a # (hash) character at the start of the line.
(New installations only) Find the database connection details for SQL Server ( or PostgreSQL), and uncomment the lines by deleting the # (hash) character at the start of the line.
(New installations only) Set the username and password to connect to the database, and delete the left [ and right ] brackets:
database.username=[your-db-user]
database.password=[your-db-password]
Set the database connection URL, which describes the location and connection details of the external database.

Step 6: Initialize the new database

The next step is to initialize the new database, creating the required database tables and initial data. To initialize the database:

On the server, open a command prompt. (If you see ‘Access Denied’ errors, run the command prompt as an Administrator).
On Linux or Mac, use su or equivalent to become the identity of papercut. e.g.
Mac: sudo su - papercut
Linux: su - papercut
Change (cd) to the server binaries directory. e.g.
Windows: cd "C:\Program Files\PaperCut NG/MF\server\bin\win"
Mac: cd "/Applications/PaperCut NG/MF/server/bin/mac"
Linux (64-bit): cd ~papercut/server/bin/linux-x64
Run the following command: db-tools init-db.

A message is displayed to indicate that the connection details are correct and the database was initialized correctly.

Step 7: Load the data into the new database

This step loads the data (that was exported in Step 2) into the database. To import the data:

On the server, open a command prompt. (If you see ‘Access Denied’ errors, run the command prompt as an Administrator).
On Linux or Mac, use su or equivalent to become the identity of papercut. e.g.
Mac: sudo su - papercut
Linux: su - papercut
Change (cd) to the server binaries directory. e.g.
Windows: cd "C:\Program Files\PaperCut NG/MF\server\bin\win"
Mac: cd "/Applications/PaperCut NG/MF/server/bin/mac"
Linux (64-bit): cd ~papercut/server/bin/linux-x64
Run the following command: db-tools import-db "backup file name". This command shows the data import progress.

If no errors occur, the application is ready to restart.

Step 8: Restart PaperCut NG/MF

The data is now in the new database and you can restart the server.