.. /*  
    * This file is part of the SavaPage project <https://www.savapage.org>.
    * Copyright (c) 2026 Datraverse B.V.
    * Author: Rijk Ravestein.
    *
    * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. <info@datraverse.com>
    * SPDX-License-Identifier: CC-BY-SA-4.0
    *
    * For more information, please contact Datraverse B.V. at this
    * address: info@datraverse.com
    */

.. _ch-external-db-migration:

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 migration steps:

.. contents:: 
   :depth: 2
   :local:


Step 1 - Stop |PRODUCT_NAME|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 :ref:`Stopping and Starting the Server <app-tools-start-stop>`.

Step 2 - Create a Backup
~~~~~~~~~~~~~~~~~~~~~~~~

Run the command to backup the current (internal) as described in
:ref:`db-export and db-export-to <app-tools-savapage-db-export>`. 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.

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.

Step 4 - Change SavaPage Connection Parameters
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Open a terminal session on the SavaPage server as user ``savapage`` and edit
the :ref:`server.properties <ch-install-on-linux-config-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 |PRODUCT_NAME|
     | 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:

.. code-block:: ini

   #------------------------------------------------------------
   # 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


Step 5 - Initialize new Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This step creates the required database tables and initial data. Open a
terminal session on the SavaPage server as user ``savapage`` and run the
command as described in :ref:`db-init <app-tools-savapage-db-init>`.

Step 6 - Restore Backup into new Database
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This step restores the backup file exported in one of the previous
steps, into the newly initialized database. Open a terminal session on
the SavaPage server as user ``savapage`` and run the command as described in
:ref:`db-import <app-tools-savapage-db-import>`.

Step 7 - Restart |PRODUCT_NAME|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

At this point the data have been migrated to the new database and the
server can be restarted.
See :ref:`Stopping and Starting the Server <app-tools-start-stop>`.

Wait a couple of seconds before logging in to the
:ref:`Admin Web App <ch-webapp-admin-login>` to verify
that the migration worked successfully.