.. /*  
    * 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:

.. figure:: ../images/manual/savapage-logo-no-text-100px.png
   :width: 75px

Using an External Database
==========================

.. admonition:: |ADMONITION_TABLE_OF_CONTENTS|

   - :numref:`{number}. {name} <ch-external-db-intro>`
   - :numref:`{number}. {name} <ch-external-db-supported>`
   - :numref:`{number}. {name} <ch-external-db-migration>`


.. _ch-external-db-intro:

Introduction
------------

By default SavaPage is packaged with `Apache Derby <https://db.apache.org/derby/>`__ 
as *internal* database. This gives you the opportunity to evaluate SavaPage on 
a small scale right away. However, in a production environment with multiple users,
we strongly advise you to use `PostgreSQL <https://www.postgresql.org/>`__
as *external* database server.

.. warning::

   Using the internal database in situations with multiple users and
   thus concurrent use, will inevitably lead to locking, deadlock and
   out-of-memory errors, which can make the system totally unresponsive.
   See our notes on :ref:`Database Locking <ch-install-on-linux-config-db-locking>`.

Other situations can be extra reason to choose for an external database,
like:

-  Organizational policy dictates that all applications must be
   consolidated on a single database infrastructure.

-  You want to take advantage of existing maintenance and backup
   procedures that are present on your current database infrastructure.

-  You want to use third party reporting tools to view and analyze the
   SavaPage database.

-  You want optimal (tailored) performance, since SavaPage is
   intensively used by a very large user population. So, for example,
   you want to deploy a dedicated database server as a scalable
   solution.

This chapter describes how to connect and migrate to an external database. For database tuning,
see :ref:`Database Connection Settings <ch-install-on-linux-config-database-connection-settings>`.

.. _ch-external-db-supported:

Supported Databases
-------------------

SavaPage is able to use any database that has a JDBC driver
available that is supported by Hibernate Dialects [1]_. *However,
PostgreSQL on GNU/Linux servers is our first choice*. PostgreSQL is
designed to be highly scalable, is optimized for concurrent use, and
handles datasets of any size efficiently. It behave robust with
thousands of users and is very well suited for large scale |PRODUCT_NAME|
implementations. Above that, PostgreSQL is Free and Open Source
software, and complies to Open Standards.

.. note::

   Of course it is possible to connect SavaPage to your existing
   database infrastructure other than PostgreSQL. For example, an Oracle
   JDBC connection template is present in
   :ref:`server.properties <ch-install-on-linux-config-server-properties>`.
   Contact your :ref:`SavaPage Service Provider <ch-webapp-admin-about-support>`
   to assist you with configuring alternative connections.

.. [1]
   `Hibernate <https://hibernate.org/>`__ is an object-relational
   mapping tool for the Java programming language. It provides a
   framework for mapping an object-oriented domain model to a relational
   database. Hibernate supports several SQL Dialects. Each dialect
   specifies the database type and is responsible for connecting to the
   database and generating the appropriate SQL statements.