The Database Tool or DBTool is used for maintenance and other database operations.
It is included with every installation of the database service or can be installed as an individual component. DBTool.exe is located in the EasyPost® Mailroom installation folder.
DBTool.exe will determine which database service to connect to, based upon the connection string in the mailroom configuration. If no configuration is available i.e. the tool is installed on a database server where no mailroom is installed, the default values will be used which would resolve to the current user’s database on the local machine.
Bing recommends regular scheduled database backups for data protection and recovery.
Usage and Options
DBTool.exe can be used with various arguments to perform different database tasks. Each main option may have additional sub-options. Several main options can be specified at the same time and some can be repeated several times with different sub-options. Regardless of the order of the main options provided in the command line the operations are always executed in the sequence displayed here (ne, usr, help, log, auto, db, backup, restore, migrate, clean, copy_settings, copy_packs). To view main option specific information use the help command below.
| -ne | Suppress privileges elevation. |
| -h -help -? | Display information for a specific main option. Example: "dbtool -h b" will display backup options. |
| -l -log | Specify full file path where to log all output. |
| -auto | Automatically answer all questions. Can be used for unmanned executions. |
| -db | Explicitly specify target database name. |
| -b -backup | Backup database. |
| -m -migrate | Migrate old version database. |
| -r -restore | Restore database from a backup. |
| -c -clean | Clean database of unused data. |
| -cs -copy_settings | Copy user specific information. |
| -cp -copy_packs | Copy mailings from other database. |
-ne
Suppress privileges elevation. Some operations may fail if not running with elevated privileges (this option is ignored if already running with elevated privileges).
By default DBTool will prompt for elevated privileges on every operation performed. It is possible to suppress elevation by providing the -ne option. The following operations permit use of -ne option:-
-l
-auto
-b
-m (when folder option is not used and basepath is specified and not fixing the INI)
-c
-cs (when source user/host is given and target user/host is not)
-cp
-l -log
File path for log output. The only argument is a full path to a log file which will be used to record all console output. The destination file will be overwritten! If this option is not specified the default log file is "DBTool.log" located in the current Mailroom temporary folder.
"dbtool -l "C:\logs\DBTool.log" ..."
will copy all console output to the specified file.
-auto
Automatically answer all questions. Possible arguments are "yes" or "no".
"dbtool -auto no"
will set "no" as the answer to any question.
-db
Explicitly specify target database name. If this option is not provided, the database as specified in the Mailroom configuration for the current user is used. The target database service is always the one specified in the Mailroom configuration (default is the local host on the default port), so the target database server cannot be changed with this option.
The only argument is the database name.
"dbtool -db ""
will execute all commands against the root (default) database.
dbtool –db usera
will execute all commands against the usera database.
-b -backup
Backup the database without locking it and truncate transaction logs. The created backup will be current as at the time the operation was started, but may include some data modified during the backup operation. If backup path is provided the target database service must be on the local machine. The operation will override any previous backup stored in the same location.
Possible sub-options are:
-b_all
backup all databases. When this option is specified the target db option is ignored and if <backup path> is provided, it is assumed to be a folder path.
<backup path>
Absolute path in which to store the backup. If this option is not used the backup will be stored in a preconfigured location. It can point to existing folder, otherwise it is assumed to specify a file or folder depending on the -b_all option.
A predetermined file name and/or extension is appended automatically when necessary.
dbtool -b "C:\MailroomBackups\20170101\db.epbak"
Backs up the current database to file db.epbak
dbtool -b "C:\MailroomBackups\20170101"
If folder 20170101 exists, the current database is backed up to file "C:\MailroomBackups\20170101\dbname.epbak", if not, backup "C:\MailroomBackups\20170101.epbak" is created.
dbtool -b -b_all
Backs up all databases to default backup location e.g. "C:\ProgramData\EasyPost\db\db.backup\usera.epbak" "…db.backup\userb.epbak" etc.
dbtool -db usera -b
Backs up database usera to default location.
-m -migrate
Migrate legacy (pre version 5) databases into version 5 format.
To consolidate v5 databases, or to import mailing packs and settings from a database to a specific v5 database use -cp to copy mailing packs, and -cs to copy settings. Alternatively Mailings can be exported and imported through the Mailroom user interface. See How to Export and Import.
Migrate is commonly used after a Mailroom upgrade, but can be run at any time.
Migrate option will use epclient.ini configuration file to locate databases using the basepath field.
Note. The current database as configured in the epclient.ini is NOT the target. The target database is determined by the relative path of the source database.
e.g. shared sales database with epclient.ini config "basepath=\\server\share\sales" will migrate to the root database on server because the full relative path is in the ini file. To maintain and keep the sales database name you would run the command below rather than let the ini determine the target. All databases under \\server\share would be enumerated and migrated to.
dbtool -m \\server\share\
To maintain database names it is often better to relocate legacy database directories and explicity migrate them 1 by 1.
If no basepath is found, migrate will enumerate and migrate ALL local databases in default location under user folders "c:\users\..."
Mailing data or user information will be overwritten if it already exists in the target database.
Possible sub-options are:
-m_dont_fix_config
Suppress Mailroom configuration file update to the new version format. By default some configuration values are adjusted after migration.
<folder path>
A folder where to look for old database(s). Additionally all sub-folders (if any) are traversed and migrated to corresponding databases with the subfolder relative path used as database name.
Example 1 – standalone local database, no basepath
dbtool -m
Migrate connects to local database service. User folders (C:\Users\...\AppData\Local\EPMailroom\DB) are searched for old databases and each is migrated to a new database named after the corresponding username e.g. localhost\usera.
Example 2 – standalone database(s), remote host, basepath = \\server\share
dbtool -m
Migrate connects to remote database service on server and migrates the current user’s database from \\server\share\usera to server\usera
dbtool –m \\server\share\databases\usera
will migrate usera's database to the root database. Multiple databases can be consolidated to a single database in this way.
Additionally multiple databases can be combined using a single command e.g.
dbtool -m \\server\share\databases\usera –m \\server\share\databases\userb
will migrate usera and userb databases into the root database.
Example 4 – local specific databases
dbtool -m c:\temp\database\depta
will migrate database depta to the root database.
dbtool -m c:\temp\database
will maintain the database name depta because of the relative path.
-r -restore
Restore database from a backup. This operation will attempt to lock the database and overwrite any existing data. The default backup file is used to restore the data from, unless a full path to a backup file is specified as an additional argument. If backup file is provided the database service must be on the local machine.
Target database can also be specified with -db.
Example 1
dbtool -r C:\MailroomBackups\20150101\db.epbak
Restore the current database from a backup stored in C:\MailroomBackups\20150101\db.epbak.
Example 2
dbtool -db "" -r
Restores the root database backup to the root database.
Example 3
dbtool -db usera -r
Restores usera database backup to the usera database.
Example 4
dbtool -r
Restores the current user database backup to the current user database.
Example 5
dbtool -db archive -r C:\MailroomBackups\root.db.epbak
Restores the root database to an archive database.
-c -clean
Clean the database of unused data without locking the database. Any deleted items and unreferenced data will be permanently removed. It is possible to specify old submitted mailings to be removed as well:
+N will delete mailings older than N days.
dd/mm/yyyy will delete mailings older than the specified date. The date format is <day in month>/<month from 1 to 12>/<full year>
For example
dbtool -c +90
will delete all submitted mailings older than 90 days and remove unreferenced data.
dbtool -c 01/12/2016
will delete all submitted mailings created before 01/12/2016 and remove unreferenced data.
-cs -copy_settings
Copy user settings from one user to another. The target user settings are overridden. If source user and host are not specified all settings are copied (and overridden!). All sub-options are ignored in this case.
When source user/host are provided only the specified settings are copied to the target user/host. If target user/host are not given they are defaulted to the current user settings specified in the Mailroom configuration.
Mapping to/from "Shared User Settings" in the Mailroom configuration:
0 (shared between all computers and users) <=> both host and user are not used
1 (shared between users on each computer) <=> only host is used
2 (shared between computers for each user) <=> only user is used
3 (not shared) <=> both user and host are used.
Copy settings always targets the current database as per epclient.ini
Possible sub-options are:
-cs_presets_only
Only copy the presets. If this option is not specified all user settings including registration data are copied.
-cs_src_db <db>
Specify the source database to copy the settings from. If not specified the same (target) database is used. <db> can be folder path to old version database or database connection string.
-cs_src_user <user>
The user name of the user to copy the settings from. Use "?" if the user name was not used to store the settings.
-cs_src_host <host>
The host name used to store the source settings. Can be omitted if it was not originally used.
-cs_target_user <user>
The user name of the user to copy the settings to. Use "?" if the user name should not be used to store the settings.
-cs_target_host <host>
The host name used to store the settings. Can be omitted if it should not be used.
Examples:
dbtool -cs -cs_src_db "localhost\john"
will copy all user settings from the database "john" on the local machine into the current user database.
dbtool -cs -cs_presets_only -cs_src_user "john" -cs_src_host "johnsLaptop"
will override the current user presets with the presets data for john (on his laptop) who is using the same database service.
dbtool -cs -cs_src_db "\\server\share_db" -cs_src_user "john" -cs_target_user "?"
will copy the settings for john, which were stored with shareusersettings=2, from an old version 4.x database at \\server\share_db. The copy will be stored into the current database in the global user settings, which are used when shareusersettings=0.
-cp -copy_packs
Copy mailings from other database. If no restrictions are specified all mailings will be copied. If a mailing already exists in the target database and is locked it will not be overridden.
Copy packs always targets the current database as configered in epclient.ini Dbtool can connect to remote database servers.
Possible sub-options are:
-cp_src_db <db>
Specify the source database to copy the packs from. <db> can be folder path to old version database or database connection string.
-cp_start_date <dd/mm/yyyy>
The minimum creation date for the source mailings.
-cp_end_date <dd/mm/yyyy>
The upper boundary for creation date for the source mailings.
dbtool -cp -cp_src_db "dbserver\john"
Will copy all mailings from database "john" on host dbserver. To restrict packs to a date range use the following example.
dbtool -cp -cp_src_db "dbserver\john" -cp_start_date 01/01/2018 -cp_end_date 31/12/2018
For a remote root database use
dbtool -cp -cp_src_db dbserver\
For a local database use localhost.
dbtool -cp -cp_src_db localhost\otherdb
Copying packs and settings from legacy to specific v5 database
Configure your epclient.ini to the database you wish to import into and then run
dbtool –cp –cp_src_db "\\server\share_db"