.. /* * This file is part of the SavaPage project . * Copyright (c) 2026 Datraverse B.V. * Author: Rijk Ravestein. * * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. * SPDX-License-Identifier: CC-BY-SA-4.0 * * For more information, please contact Datraverse B.V. at this * address: info@datraverse.com */ .. _app-tools-savapage-db: Database Commands ----------------- .. contents:: |RST_TABLE_OF_CONTENTS| :depth: 1 :local: .. _app-tools-savapage-intro: Introduction ~~~~~~~~~~~~ The ``savapage-db`` command-line tool provides functions for manipulating the database. The tool is located in ``/opt/savapage/server/bin/linux-x64/`` and needs to be executed from a command prompt. The syntax of the command is: .. code-block:: text :caption: savapage-db usage: [OPTION] --db-check Checks database integrity. This is an advanced option. Please contact SavaPage Support before use. --db-check-fix Checks and fixes database integrity. NOTE: Only perform as requested by SavaPage Support. --db-config-get Gets configuration property value. This is an advanced option. Please contact SavaPage Support before use. --db-config-set Sets configuration property value. This is an advanced option. Please contact SavaPage Support before use. --db-delete-logs Deletes application, account transaction and document log data older than DAYS. A DAYS value of zero (0) will remove all log data from the system. --db-export Exports the database to the default backup location. --db-export-to Exports the database to the specified file or directory. --db-import Imports the database from the specified file. Deletes any existing data before loading the data. --db-init Re-initializes the database even if it already exists. --db-run-script Runs SQL statements from the specified script file. NOTE: Only perform as requested by SavaPage Support. --db-run-sql Runs an SQL statement. NOTE: Only perform as requested by SavaPage Support. --db-schema-version Echoes database schema version on stdout. -h,--help Displays this help text. --log4j Use log4j. NOTE: Only perform as requested by SavaPage Support. The command must be run as the ``savapage`` user. An example: .. code-block:: bash sudo su - savapage cd server/bin/linux-x64 ./savapage-db --db-import /home/john/savapage-backup.zip .. important:: ``savapage-db`` needs exclusive access to the database. It is important that any SavaPage services and processes are stopped before executing a command. Failure to do so will result in a "database in use" error message. .. caution:: The ``savapage-db`` command is a powerful low-level utility and its use on a production system should be carefully considered. Consult your SavaPage Service Provider before taking any actions that affect the structure and content of the database. Details of ``savapage-db`` commands are discussed below. .. _app-tools-savapage-db-check: db-check ~~~~~~~~ Checks database integrity. This is an advanced option. Please contact SavaPage Support before use. .. _app-tools-savapage-db-check-fix: db-check-fix ~~~~~~~~~~~~ Checks and fixes database integrity. .. note:: Only perform as requested by your SavaPage Service Provider. .. _app-tools-savapage-db-config-get: db-config-get ~~~~~~~~~~~~~ With this option the (decrypted) value of a :ref:`Configuration Property ` can be retrieved. Also see :ref:`getConfigProperty `. .. _app-tools-savapage-db-config-set: db-config-set ~~~~~~~~~~~~~ With this option the value of a :ref:`Configuration Property ` can be set (and encrypted). Also see :ref:`setConfigProperty `. .. _app-tools-savapage-db-delete-logs: db-delete-logs ~~~~~~~~~~~~~~ This option delete old log data from the system. This command will permanently delete the following data. - Document logs - Record all document history and statistics - Transaction logs - Record all financial history and statistics - Application logs - Record application status and error messages The DAYS option determines what data will be deleted. If DAYS is 90, then all log data more than 90 days old will be deleted. A value of zero (0) will remove all historical log data from the system. This is an example: .. code-block:: bash savapage-db --db-delete-logs 90 .. _app-tools-savapage-db-export: db-export and db-export-to ~~~~~~~~~~~~~~~~~~~~~~~~~~ This option exports the data from the database. The application server must be stopped before performing the export. See :ref:`Stopping and Starting the Server `. .. tip:: If you want to perform an online backup without stopping the application server you can use the backup function in the Admin Web App. See :ref:`Backups `. .. callout:: .. code-block:: bash :caption: example savapage-db --db-export # <1> savapage-db --db-export-to /home/john # <2> savapage-db --db-export-to /home/john/savapage-backup.zip # <3> .. annotations:: :1: The database export file is created in the ``/opt/savapage/server/data/backups`` directory and the file is named ``savapage-export-[date-time].zip``. :2: This option is used to override the default backup directory. The filename will still be named ``savapage-export-[date-time].zip``. :3: The full path and filename where the backup is saved is specified. .. note:: When executing the command the last line echoed to ``stdout`` is the canonical path of the database export file. .. tip:: The database export zip file contains an unformatted XML file with the database content (tables and rows). An XML formatter can be enabled by setting configuration item ``system.backup.xmlformatter.enable`` to ``Y``. See |RST_LINK_CONFIG_EDITOR| on how to set this property. .. caution:: If the directory or filename parameters contain spaces, then the argument needs to be quoted. .. _app-tools-savapage-db-import: db-import ~~~~~~~~~ This option imports the data (from a previous export) into the database. The application server must be stopped to perform the import. This is an example: .. code-block:: bash savapage-db --db-import /home/john/savapage-backup.zip .. note:: Progress and statistics of the import process are written to ``stdout``. .. warning:: Before import the database is initialized. Thereby existing data in the database are erased. .. _app-tools-savapage-db-init: db-init ~~~~~~~ This option initializes a database, creating the required tables and initial data. The application server must be stopped before you initialize the database. This is the command: .. code-block:: bash savapage-db --db-init .. warning:: Be careful, existing data in the database are erased.