PaperCut - Upsizing to an External RDBMS

Upsizing to an external RDBMS is a simple process that should take approximately 15-30 minutes. The high-level steps to upsize are: 1. 2. 3. 4. Backup the existing data. Create and initialize the new database. Load the backed-up data into the new database. Restart the application.

These steps are discussed in detail below. This chapter also includes some sections that describe database specific configuration. See the section called Database specific configuration for more details.

Important
Each application server requires exclusive access to an external database. i.e. A single database cannot be shared between more than one application server. If you are running multiple application servers (e.g. a test and production instance), then each must have a separate database.

Step 1 - Stop PaperCut NG

To upsize to an external database the application server must be stopped. This allows the data to be backed up, guaranteeing that all data is saved and ready to load into the new database. The instructions to stop the application server can be found in the section called Stopping and Starting the Application Server.

Step 2 - Perform a backup of the existing data

Perform a backup of the database. This data will be loaded into the application in a following step. A detailed discussion about backups can be found in the section called System Backups. To backup the database: 1. On the server, open a command prompt. 2. If running on Linux or Mac, use su or equivalent to become the identity of papercut. e.g. 3. Mac: sudo su - papercut 4. Linux: su - papercut

5. Change (cd) to the server binaries directory. e.g. 6. Windows: cd "C:\Program Files\PaperCut NG\server\bin\win" 7. Mac: cd "/Applications/PaperCut NG/server/bin/mac" 8. Linux: cd ~papercut/server/bin/linux-*

9. Run the following command: db-tools export-db 10. The output of the above command shows the name of the backup file created. Take note of this because it will be required in a future step.

Step 3 - Create a new database in the external RDBMS

This step depends on the external database you are using, and it is assumed that the administrator knows how to create a new database. No matter what database is used the following steps must be performed: 1. Create a new empty database for dedicated use by PaperCut NG. When creating the database make sure to select the correct character encoding for your language. IMPORTANT: The database should be created with an character encoding suitable for your language. For SQL Server, the character encoding is set in the Collation field on the new database screen. For other databases like PostgreSQL or MySQL it is recommended to select a unicode character set (like UNICODE or UTF8) that allows all possible characters to be stored. 2. Create a new database user (and password) for the PaperCut NG to use to connect to the database. 3. Assign the appropriate permissions to the new user to give them full access to the new database (e.g. permission to create/drop tables, and select/insert/update/delete in all tables).

Important
To use SQL Server you must ensure that SQL Server has the TCP protocol, and the server authentication option is set to "SQL Server and Windows Authentication".

Important
The database user created for PaperCut NG should only have minimal set of permissions required for the PaperCut application. The user should have full permissions to create/drop tables and have full access to any created tables. However, the user should not have permissions to access other databases installed on the database server.

Step 4 - Change the PaperCut NG connection details

The next step is to configure PaperCut NG to connect to the new external database. To do this: 1. On the server, open the server config file: 2. [app-path]/server/server.properties

in a text editor (e.g. Notepad). 3. Comment out the line: 4. database.type=Internal

by adding a # (hash) character to the beginning of the line. 5. Find the database connection details for the database type you require (e.g. SQL Server or PostgreSQL), and uncomment the lines by removing the # (hash) characters. 6. Set the username and password used to connect to the database 7. database.username=[your-db-user] 8. database.password=[your-db-password]

9. Set the database URL, which describes the location and connection details of the external database. See below for details of the format of the database URLs for different database types.

Important
If using Microsoft SQL Server, the username specified in the configuration settings is a SQL Server database user, not a Windows user. This user needs to be created in the SQL Server and granted full rights to the application database.

SQL Server Database Connection URL Format

The SQL Server URL format is: jdbc:jtds:sqlserver://[server]/[database]

The [server] parameter is the name of the server running the SQL Server database, and must be resolvable from the PaperCut NG server. If the SQL Server instance is running on the same machine then localhost can be used. The [database] parameter is the name of the SQL Server database you created in Step 3 above. When using SQL Server instances, the instance name is specified in the connection URL as follows: jdbc:jtds:sqlserver://[server]/[database];instance=[instancename]

SQL Server Express Database Connection URL Format

The SQL Server Express format is: jdbc:jtds:sqlserver://[server]:[port]/[database]

The [server] parameter is the name of the server running the SQL Server database, and must be resolvable from the PaperCut NG server. If the SQL Server instance is running on the same machine then localhost can be used. The [port] parameter is the port the SQL Server Express edition is configured to listen on. For more information on configuring SQL Express, please see the section called Configuring Microsoft SQL Express. The [database] parameter is the name of the SQL Server database you created in Step 3 above.

PostgreSQL Database Connection URL Format

The Postgres URL format is:

jdbc:postgresql://[server]/[database]

The [server] parameter is the name of the server running the PostgreSQL database, and must be resolvable from the PaperCut NG server. If the PostgreSQL instance is running on the same machine then localhost can be used. The [database] parameter is the name of the PostgreSQL database you created in Step 3 above.

MySQL Database Connection URL Format

The MySQL URL format is: jdbc:mysql://[server]/[database]

The [server] parameter is the name of the server running the MySQL database, and must be resolvable from the PaperCut NG server. If the MySQL instance is running on the same machine then localhost can be used. The [database] parameter is the name of the MySQL database you created in Step 3 above.

Important
See the section called Configuring MySQL for specific instructions to configure MySQL.

Oracle Database Connection URL Format

The Oracle URL format is: jdbc:oracle:thin:@[server]:[port]/[SID]

The [server] parameter is the name of the server running the Oracle database, and must be resolvable from the PaperCut server. If the Oracle instance is running on the same machine then localhost can be used. The [port] specifies the port number that the Oracle services are listening on. By default this is 1521. The [SID] specifies the Oracle service identifier used to identify the database. The SID for Oracle Express edition is XE. E.g. for an Oracle Express Edition installation on the same server as PaperCut, running on the default port and SID, use: jdbc:oracle:thin:@localhost:1521/SE

Important

See the section called Configuring Oracle (and Oracle Express Edition) for specific instructions to configure Oracle.

Step 5 - 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: 1. On the server, open a command prompt. 2. If running on Linux or Mac, use su or equivalent to become the identity of papercut. e.g. 3. Mac: sudo su - papercut 4. Linux: su - papercut

5. Change (cd) to the server binaries directory. e.g. 6. Windows: cd "C:\Program Files\PaperCut NG\server\bin\win" 7. Mac: cd "/Applications/PaperCut NG/server/bin/mac" 8. Linux (32bit): cd ~papercut/server/bin/linux-i686 9. Linux (64bit): cd ~papercut/server/bin/linux-x64

10. Run the following command: db-tools init-db A message will be displayed to indicate that the connection details are correct the database was initialized correctly.

Step 6 - 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: 1. On the server, open a command prompt. 2. If running on Linux or Mac, use su or equivalent to become the identity of papercut. e.g. 3. Mac: sudo su - papercut 4. Linux: su - papercut

5. Change (cd) to the server binaries directory. e.g. 6. Windows: cd "C:\Program Files\PaperCut NG\server\bin\win" 7. Mac: cd "/Applications/PaperCut NG/server/bin/mac" 8. Linux (32bit): cd ~papercut/server/bin/linux-i686 9. Linux (64bit): cd ~papercut/server/bin/linux-x64

10. Run the following command: db-tools import-db "backup file name" 11. This command will show progress importing the data. If no errors occurred then the application is ready to restart.

Step 7 - Restart PaperCut NG

The data has now been moved to the new database and the server can be restarted. The instructions on how to start the server can be found in the section called Stopping and Starting the Application Server. Wait 30 seconds for the server to start, then log in to the admin console. If you can log in successfully, then the upsizing process worked successfully.