The zendhqctl database Module

The zendhqctl database command is used to test and migrate ZendHQ databases of your ZendHQ installation. Use cases of these database commands are database migration and disaster recovery. For more usage information and warnings, see ZendHQ Database Configurations.

zendhqctl database configuration

The command zendhqctl needs access to the ZendHQ database without running the ZendHQ daemon. By default, the command uses the default ZendHQ configuration file ${INSTALL_PREFIX}/etc/zendhqd.ini for the database configuration.

If you are using a different ZendHQ configuration file, specify the name of the file with the -c, --config-file your_path command-line argument, or with the ZENDHQ_CONFIG_FILE environment variable.

For example:

zendhqctl -c /opt/zend/zendphp/etc/zendhqd_current.ini module ...

Or:

export ZENDHQ_CONFIG_FILE=/opt/zend/zendphp/etc/zendhqd_current.ini 
		zendhqctl module ...

Replace module ... by, for example, database migrate and so on, to use database commands.

Commands

The test command

zendhqctl database test [-t|--table-prefix prefix]

Use this command to test the database configuration by opening the connection, creating a test table prefix_test, inserting data into the table, and then dropping the table. The default test table prefix is zendhqctl.

• -t or --table-prefix

  (Optional) Define a custom table prefix for the test table.

The export command

zendhqctl database export
    [-y|--yes] 
    [-f|--file <path>]

Exports the ZendHQ database from the existing database engine configured in the ZendHQ daemon's configuration file to the standard output or to the specified file. The output of the command can be used as an input for the import command.

• -y or --yes

  (Optional) Answer yes to any prompts

• -f <path> or --file <path>

  (Optional) Specify the file to export the database to. If not specified, the database will be exported to the standard output.

For example, to export the ZendHQ database to the file zendhq_db_export.txt:

zendhqctl database export -f zendhq_db_export.txt

For example, to export the ZendHQ database to the standard output using gzip to compress:

zendhqctl database export | gzip > zendhq_db_export.txt.gz

The import command

zendhqctl database import 
    [-y|--yes] 
    [-f|--file <path>] 
    [-n|--dry-run] 
    [-r|--retain-i-values]

Imports the ZendHQ database from the standard input or from the specified file to the existing database engine configured in the ZendHQ daemon's configuration file. The input of the command must be the output of the export command. All the existing data in the database will be lost.

• -y or --yes

  (Optional) Answer yes to any prompts. Notice that reading from the standard input implies that the command will not prompt for confirmations.

• -f <path> or --file <path>

  (Optional) Specify the file to import the database from. If not specified, the database will be imported from the standard input.

• -n or --dry-run

  (Optional) Perform a dry run with the without importing the database. The command will execute all the necessary steps including database cleanup and insert statements, but will not commit the transaction.

• -r or --retain-id-values

  (Optional) Retain the original ID values of some of the imported data (users, groups, JobQueue queues). On MySQL and MariaDB, the option may cause database corruption if the import fails due to the inability to roll back the transaction. Use with caution and ensure that the database is backed up before importing the data.

Initialize the ZendHQ database by running the ZendHQ daemon at least once or with the zendhqd -c <config> --init-only command before importing the data.

For example, to import the ZendHQ database from the file zendhq_db_export.txt:

zendhqctl database import -f zendhq_db_export.txt

For example, to import the ZendHQ database from the standard input using gzip to decompress:

gzip -d zendhq_db_export.txt.gz | zendhqctl database import

The migrate command

zendhqctl database migrate
    [-y|--yes]
    [-k|--keep-migration-file]
    FROM [TO]

Use this command to migrate the ZendHQ database from the existing database engine configured in FROM to the new ZendHQ database configured in the main ZendHQ configuration file or a custom location.

• FROM

  The path to the existing database engine to migrate. For example, /opt/zendhqd_sqlite.ini.

• TO

  (Optional) A new custom path where to store the new ZendHQ database.

• -y or --yes

  (Optional) Automatically answer yes to all prompts. Useful for a silent installation.

• -k or --keep-migration-file

  (Optional) Keep the temporary migration file.

Initialize the new ZendHQ database by running the ZendHQ daemon at least once with the new configuration or with the zendhqd -c <config> --init-only command before migrating the data.

For example, to migrate data from the existing SQLite database configured in /opt/zend/zendphp/etc/zendhqd_sqlite.ini to a new database configured in the main ZendHQ daemon's configuration file, use the following command:

zendhqctl database migrate /opt/zend/zendphp/etc/zendhqd_sqlite.ini

For example, to migrate the ZendHQ database from the existing SQLite database configured in the file zendhqd_sqlite.ini to the new PostgreSQL database configured in the file zendhqd_pgsql.ini:

zendhqctl database migrate /opt/zend/zendphp/etc/zendhqd_sqlite.ini /opt/zend/zendphp/etc/zendhqd_pgsql.ini

The drop command

zendhqctl database drop
    [-y|--yes]
    [-n|--dry-run]

Drops all the ZendHQ database tables.

• -y or --yes

  (Optional) Answer yes to any prompts.

  This command is irreversible and deletes all data from the ZendHQ database.

• -n or --dry-run

  (Optional) Perform a dry run without actually dropping the tables.

This command drops only database tables, indexes and views created by the ZendHQ daemon. It does not drop the database itself nor delete SQLite database files.

For example, to drop all the ZendHQ database tables:

zendhqctl database drop