Starting and Stopping HAWQ

In a HAWQ DBMS, the database server instances (the master and all segments) are started or stopped across all of the hosts in the system in such a way that they can work together as a unified DBMS.

Because a HAWQ system is distributed across many machines, the process for starting and stopping a HAWQ system is different than the process for starting and stopping a regular PostgreSQL DBMS.

Use the hawq startobject and hawq stopobject commands to start and stop HAWQ, respectively. These management tools are located in the $GPHOME/bin directory on your HAWQ master host. Initializing a HAWQ system also starts it.


Do not issue a KILL command to end any Postgres process. Instead, use the database command pg_cancel_backend().

For information about hawq start and hawq stop, see the appropriate pages in the HAWQ Management Utility Reference or enter hawq start -h or hawq stop -h on the command line.

Initialize HAWQ

Initialize and start the HAWQ system using configuration parameters defined in $GPHOME/etc/hawq-site.xml.

The hawq init command with the appropriate cluster or node command initializes and starts a HAWQ cluster. The master or segment nodes can be individually initialized by using hawq init master and hawq init segment commands, respectively. Format options can also be specified at this time.

The hawq init <object> utility will create a HAWQ instance using configuration parameters defined in $GPHOME/etc/hawq-site.xml A single node cluster can be started without any user-defined changes to the default hawq-site.xml file. Use the template-hawq-site.xml file to specify the configuration for larger clusters.

When using the template for initializing a new cluster configuration, replace the items contained within the % markers, for example in:, would be replaced with the master host name. After modification, rename the file to the name of the default configuration file: hawq-site.xml.

  • Before initializing HAWQ, set the $GPHOME environment variable to point to the location of your HAWQ installation on the master host and exchange SSH keys between all host addresses in the array, using hawq ssh-exkeys.
  • To initialize and start a HAWQ cluster, enter the following command on the master host:

    $ hawq init cluster

Starting HAWQ

Start an initialized HAWQ system by running the hawq start command on the master instance.

Use the hawq start cluster command to start a HAWQ system that has already been initialized by the hawq init cluster command, but has been stopped by the hawq stop cluster command. The hawq start cluster command starts HAWQ by starting all the segments on the HAWQ cluster. hawq start cluster orchestrates this process and performs the process in parallel.

You can also use the hawq start master command to start only the HAWQ master, without segment nodes, then add these later, using hawq start segment. If you want HAWQ to ignore hosts that fail ssh validation, use the hawq start --ignore_bad_hosts option.

  • Run hawq start cluster on the master host to start a HAWQ system:

    $ hawq start cluster


    When the HAWQ system is first initialized with the hawq init command, it is automatically started.

Restarting HAWQ

Stop the HAWQ system and then restart it.

The hawq restart command with the appropriate cluster or node command can stop and then restart HAWQ after the shutdown completes. If the master or segments are already stopped, restart will have no effect.

  • To restart a HAWQ cluster, enter the following command on the master host:

    $ hawq restart cluster

Reloading Configuration File Changes Only

Reload changes to the HAWQ configuration files without interrupting the system.

The hawq stop command can reload changes to the pg_hba.conf configuration file and to runtime parameters in the hawq-site.xml file and pg_hba.conf file without service interruption. Active sessions pick up changes when they reconnect to the database. Many server configuration parameters require a full system restart (hawq restart cluster) to activate. For information about server configuration parameters, see the Server Configuration Parameter Reference.

  • Reload configuration file changes without shutting down the system using the hawq stop command:

    $ hawq stop --reload

Starting the Master in Maintenance Mode

Start only the master to perform maintenance or administrative tasks without affecting data on the segments.

Maintenance mode is a superuser-only mode that should only be used when required for a particular maintenance task. For example, you can connect to a database only on the master instance in maintenance mode and edit system catalog settings.

  1. Run hawq start using the master -m option:

    $ hawq start master -m
  2. Connect to the master in maintenance mode to do catalog maintenance. For example:

    $ PGOPTIONS='-c gp_session_role=utility' psql template1
  3. After completing your administrative tasks, restart the master in production mode.

    $ hawq restart master 


    Incorrect use of maintenance mode connections can result in an inconsistent system state. Only expert users should perform this operation.

Stopping HAWQ

The hawq stop cluster command stops or restarts your HAWQ system and always runs on the master host. When activated, hawq stop cluster stops all postgres processes in the system, including the master and all segment instances. The hawq stop cluster command uses a default of up to 64 parallel worker threads to bring down the segments that make up the HAWQ cluster. The system waits for any active transactions to finish before shutting down. To stop HAWQ immediately, use fast mode. The commands hawq stop master, hawq stop segment, hawq stop standby, or hawq stop allsegments can be used to stop the master, the local segment node, standby, or all segments in the cluster. Stopping the master will stop only the master segment, and will not shut down a cluster.

  • To stop HAWQ:

    $ hawq stop cluster
  • To stop HAWQ in fast mode:

    $ hawq stop cluster -M fast

Best Practices to Start/Stop HAWQ Cluster Members

For best results in using hawq start and hawq stop to manage your HAWQ system, the following best practices are recommended.

  • Issue the CHECKPOINT command to update and flush all data files to disk and update the log file before stopping the cluster. A checkpoint ensures that, in the event of a crash, files can be restored from the checkpoint snapshot.

  • Stop the entire HAWQ system by stopping the cluster on the master host.

    $ hawq stop cluster
  • To stop segments and kill any running queries without causing data loss or inconsistency issues, use fast or immediate mode on the cluster:

    $ hawq stop cluster -M fast
    $ hawq stop cluster -M immediate
  • Use hawq stop master to stop the master only. If you cannot stop the master due to running transactions, try using fast shutdown. If fast shutdown does not work, use immediate shutdown. Use immediate shutdown with caution, as it will result in a crash-recovery run when the system is restarted.

    $ hawq stop master -M fast
    $ hawq stop master -M immediate
  • When stopping a segment or all segments, you can use the default mode of smart mode. Using fast or immediate mode on segments will have no effect since segments are stateless.

    $ hawq stop segment
    $ hawq stop allsegments
  • Typically you should always use hawq start cluster or hawq restart cluster to start the cluster. If you do end up using hawq start standby|master|segment to start nodes individually, make sure you always start the standby before the active master. Otherwise, the standby can become unsynchronized with the active master.