Database tool (db-tools)
The db-tools command-line tool provides a variety of functionality manipulating the PaperCut NG/MF 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/MF\server\bin\win\"
db-tools delete-old-logs 90
An Apple Mac example is:
sudo su - papercut
cd "/Applications/PaperCut NG/MF/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/MF services and processes are stopped before executing any commands. Failure to do so results in a "database in use" error message. The db-tools command is a powerful low-level utility so carefully consider its use on a production system. The available commands are discussed in detail below.
export-db command
The export-db command exports the data from the database. The Application ServerAn Application Server is the primary server program responsible for providing the PaperCut user interface, storing data, and providing services to users. PaperCut uses the Application Server to manage user and account information, manage printers, calculate print costs, provide a web browser interface to administrators and end users, and much more. must be stopped before performing the export. The syntax and options for the export-db command are:
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 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.
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 is deleted first.
If the import-file contains spaces, quote this argument.
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 drops 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 permanently deletes 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 performs the deletion without confirmation from the user. This is useful when automating this deletion through a scheduled task or cron job.
The delete-older-than-days option determines what data is deleted. If delete-older-than-days is 90, then all log data more than 90 days old is deleted. A value of zero (0) removes all historical log data from the system.