Upsizing to an external RDBMS is a simple process that should take approximately 15-30 minutes. The high-level steps to upsize are:
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.
To upsize to an external database the application server should 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”.
Perform a backup of the database. This data will be loaded into the application in a future step. A detailed discussion about backups can be found in the section called “System Backups”. To backup the database:
On the server, open a command prompt.
If running 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\server\bin\win"
Mac: cd "/Applications/PaperCut NG/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 created. Take note of this because it will be required in a future step.
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:
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. 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.
Create a new database user (and password) for the PaperCut NG to use to connect to the database.
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).
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".
The database user created for PaperCut NG should only have minimal set of permissions required for the 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.
The next step is to configure PaperCut NG to connect to the new external database. To do this:
On the server, open the server config file:
[app-path]/server/server.properties
in a text editor (e.g. Notepad).
Comment out the line:
database.type=Internal
by adding a # (hash) character to the beginning of the line.
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.
Set the username and password used to connect to the database
database.username=[your-db-user]
database.password=[your-db-password]
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.
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.
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]
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.
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.
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.
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 NG 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.
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 running 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\server\bin\win"
Mac: cd "/Applications/PaperCut NG/server/bin/mac"
Linux: cd ~papercut/server/bin/linux-i686
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.
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 running 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\server\bin\win"
Mac: cd "/Applications/PaperCut NG/server/bin/mac"
Linux: cd ~papercut/server/bin/linux-i686
Run the following command: db-tools import-db "backup file name"
This command will show progress importing the data.
If no errors occurred then the application is ready to restart.
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.
© Copyright 1999-2009. PaperCut Software International Pty Ltd. All rights reserved.