17.2. Migrating to an External Database

The migration is a simple process and takes about 15-30 minutes. The sections below describe in more detail the following high-level migration scenario steps:

  1. Stop the server.

  2. Create a backup of the current internal database.

  3. Create and initialize a new external database.

  4. Restore the backup into the new external database.

  5. Restart the server.

17.2.1. Step 1 - Stop SavaPage

The application server must be stopped in order to make a backup of the current internal database. The command to stop the server is described in Section C.4, “Stopping and Starting the Server”.

17.2.2. Step 2 - Create a Backup

Run the command to backup the current (internal) as described in Section C.3.4, “db-export and db-export-to”. The command echoes the name of the created backup file to stdout. Take a note of this because you will need this in a future step.

17.2.3. Step 3 - Create new Database in External DBMS

Creating a new database is specific to the external Database Management System and is off-topic for this manual. It is assumed that the database administrator knows how to create a new database. However, the following generic requirements must be honored:

  • Create a dedicated database user with a strong password to be used by SavaPage to connect to the database.

  • Create the new empty database with a Unicode or UTF8 character encoding to make sure that all possible characters can be stored.

  • Assign the dedicated user full access to the new database, i.e. grant permission to create and drop tables, and to execute select, insert, update and delete statements in all tables.

17.2.4. Step 4 - Change SavaPage Connection Parameters

Open a terminal session on the SavaPage server as user savapage and edit the /opt/savapage/server/server.properties file.

  • Comment out the line database.type=Internal by adding a hash (#) character at the start of the line.

  • Uncomment the database. connection parameter lines for the external database (in our case PostgreSQL).

  • Set the database.url, which describes the location and connection details of the external database.

    The PostgreSQL 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 SavaPage 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 the previous step.

  • Set the database.user and database.password used to connect to the database.

A connection example is shown below:

#------------------------------------------------------------
# Database Settings
#------------------------------------------------------------

# Using the internal database (default)
#database.type=Internal

# PostgreSQL connection
database.type=PostgreSQL
database.driver=org.postgresql.Driver
database.url=jdbc:postgresql://localhost/savapage
database.user=your-db-user
database.password=your-db-user-password                    

17.2.5. Step 5 - Initialize new Database

This step initializes the new database, it creates the required database tables and initial data.

To initialize the database, open a terminal session on the SavaPage server as user savapage and run the command as described in Section C.3.6, “db-init”.

17.2.6. Step 6 - Restore Backup into new Database

This step restores the backup file exported in the previous step, into the newly initialized database. Open a terminal session on the SavaPage server as user savapage and run the command as described in Section C.3.5, “db-import”.

17.2.7. Step 7 - Restart SavaPage

At this point the data have been migrated to the new database and the server can be restarted. See Section C.4, “Stopping and Starting the Server”.

Wait a couple of seconds before logging in to the Admin Web App to verify that the migration worked successfully.