Database Tool (db-tools)

Database Tool (db-tools)
Prev	Appendix A. Tools - database, server-command scripting, and APIs (Advanced)	Next

The db-tools command-line tool provides a variety of functionality manipulating the PaperCut NG database and data. The tool is located in [app-path]/server/bin/<platform>/ and needs to be executed from a command prompt. The syntax of the command is:

            db-tools command [options]

The valid commands are:

export-db - export/backup the database data
import-db - import/restore the database data
init-db - create tables and initial data in a new database
delete-old-logs - delete old log data (transaction, print, app log, etc)

db-tools is a command-line application accessed via the Command Prompt on Windows, or a Command Shell (e.g. bash or a terminal) on Linux and Mac. On Linux or Mac the command must be run as the papercut user. Example use on the Apple Mac:

    sudo su - papercut
    db-tools import-db -f /Users/bob/papercut-backup.zip

A Windows example is:

    cd "C:\Program Files\PaperCut NG\server\bin\win\"
    db-tools delete-old-logs 90

An Apple Mac example is:

    sudo su - papercut
    cd "/Applications/PaperCut NG/server/bin/mac/"
    db-tools import-db /Users/bob/papercut-backup.zip

db-tools needs exclusive access to the database. It is important that any PaperCut NG services and processes are stopped before executing any commands. Failure to do so will result in a "database in use" error message. The db-tools command is a powerful low-level utility and its use on a production system should be carefully considered. The available commands are discussed in detail below.

export-db Command

The export-db command exports the data from the database. The application server must be stopped before performing the export. The syntax and options for the export-db command are:

Tip

If you want to perform an online backup without stopping the application server you can use the inbuilt perform-online-backup server command.

More information on the server commands is available in the section called “Server Commands (server-command)”.

    usage: db-tools export-db [options]
     -d,--dir <dir>     Exports the database to the given directory.
     -f,--file <file>   Exports the database to the given file.
     -h,--help          Displays this help.

If no options are specified then the database export file is created in the [app-path]\server\data\backups directory and the file is named export-[date-time].zip.

The --dir option is used to override the default backup directory. The filename will still be named export-[date-time].zip.

The --file option is used to specify the full path and filename where the backup is saved.

Caution

If the directory or filename parameters contains space, then the argument needs to be quoted.

import-db Command

The import-db command imports the data (from a previous export) into the database. The application server must be stopped to perform the import. The syntax and options for the import-db command are:

    usage: db-tools import-db [options] import-file
     -f,--force   Deletes any existing data before loading the data.
     -h,--help    Displays this help.

The --force option is required when the data is loaded into a database that already contains data. In this situation, the force option indicates that existing data will be deleted first.

Caution

If the import-file contains spaces this argument will need to be quoted.

init-db Command

The init-db command initializes a database, creating the required tables and initial data. The application server must be stopped before you initialize the database. The syntax and options for the init-db command are:

    usage: db-tools init-db [options]
     -f,--force   Re-initializes the database even if it already exists.
     -h,--help    Displays this help.

The --force option is required to initialize a database that already contains the tables and data. In this case the force option will drop the existing tables before recreating the tables.

delete-old-logs Command

The delete-old-logs is used to delete old log data from the system. This command will permanently delete the following data.

Printer usage logs - Record all print history and statistics
Account transactions - Record all adjustments to user and shared accounts
Application logs - Record application status and error messages

    usage: db-tools delete-old-logs [options] delete-older-than-days
     -n,--non-interactive   Perform deletion without confirmation.
     -h,--help              Displays this help.

The --non-interactive option will perform the deletion without confirmation from the user. This can be useful when automating this deletion through a scheduled task or cron job.

The delete-older-than-days option determines what data will be deleted. If delete-older-than-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.