markdown/reference/cli/admin_utilities/hawqinit.html.md.erb - hawq-docs - Git at Google

 ---
 title: hawq init
 ---

 <!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->

 The `hawq init cluster` command initializes a HAWQ system and starts it.

 Use the `hawq init master` and `hawq init segment` commands to individually initialize the master or segment nodes, respectively. Specify any format options at this time. The `hawq init standby` command initializes a standby master host for a HAWQ system.

 Use the `hawq init <object> --standby-host` option to define the host for a standby at initialization.

 ## <a id="topic1__section2"></a>Synopsis

 ``` pre
 hawq init <object> [--options]

 hawq init standby | cluster
   [--standby-host <address_of_standby_host>]
   [<options>]

 hawq init -? | --help
 ```
 where:

 ``` pre
 <object> = cluster | master | segment | standby

 <options> =
   [-a] [-l <logfile_directory>] [-q] [-v] [-t]
   [-n]
   [--locale=<locale>] [--lc-collate=<locale>]
   [--lc-ctype=<locale>] [--lc-messages=<locale>]
   [--lc-monetary=<locale>] [--lc-numeric=<locale>]
   [--lc-time=<locale>]
   [--bucket_number <number>]
   [--max_connections <number>]
   [--shared_buffers <number>]
 ```

 ## <a id="topic1__section3"></a>Description

 The `hawq init <object>` utility creates a HAWQ instance using configuration parameters defined in `$GPHOME/etc/hawq-site.xml`. Before running this utility, verify that you have installed the HAWQ software on all the hosts in the array.

 In a HAWQ DBMS, each database instance (the master and all segments) must be initialized across all of the hosts in the system in a way that allows them to work together as a unified DBMS. The `hawq init cluster` utility initializes the HAWQ master and each segment instance, and configures the system as a whole. When `hawq init cluster` is run, the cluster comes online automatically without needing to explicitly start it. You can start a single node cluster without any user-defined changes to the default `hawq-site.xml` file. For larger clusters, use the template-hawq-site.xml file to specify the configuration.

 To use the template for initializing a new cluster configuration, replace the items contained within the % markers. For example, replace `value%master.host%value` and `%master.host%` 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:

     ```shell
     $ hawq init cluster
     ```

 This utility performs the following tasks:

 -   Verifies that the parameters in the configuration file are correct.
 -   Ensures that a connection can be established to each host address. If a host address cannot be reached, the utility will exit.
 -   Verifies the locale settings.
 -   Initializes the master instance.
 -   Initializes the standby master instance (if specified).
 -   Initializes the segment instances.
 -   Configures the HAWQ system and checks for errors.
 -   Starts the HAWQ system.

 The `hawq init standby` utility can be run on either  the currently active *primary* master host or on the standby node.

 `hawq init standby` performs the following steps:

 -   Updates the HAWQ system catalog to add the new standby master host information
 -   Edits the `pg_hba.conf` file of the HAWQ master to allow access from the newly added standby master.
 -   Sets up the standby master instance on the alternate master host
 -   Starts the synchronization process

 A backup, standby master host serves as a 'warm standby' in the event of the primary master host becoming non-operational. The standby master is kept up to date by transaction log replication processes (the `walsender` and `walreceiver`), which run on the primary master and standby master hosts and keep the data between the primary and standby master hosts synchronized. To add a standby master to the system, use the command `hawq init standby`, for example: `init standby host09`. To configure the standby hostname at initialization without needing to run hawq config by defining it, use the --standby-host option. To create the standby above, you would specify `hawq init standby --standby-host=host09` or `hawq init cluster --standby-host=host09`.

 If the primary master fails, the log replication process is shut down. Run the `hawq activate standby` utility to activate the standby master in its place;  upon activation of the standby master, the replicated logs are used to reconstruct the state of the master host at the time of the last successfully committed transaction.

 ## Objects

 <dt>cluster  </dt>
 <dd>Start a HAWQ cluster.</dd>

 <dt>master  </dt>
 <dd>Start HAWQ master.</dd>

 <dt>segment  </dt>
 <dd>Start a local segment node.</dd>

 <dt>standby  </dt>
 <dd>Start a HAWQ standby master.</dd>

 ## <a id="topic1__section4"></a>Options

 <dt>-a, (do not prompt)  </dt>
 <dd>Do not prompt the user for confirmation.</dd>


 <dt>-l, -\\\-logdir \<logfile\_directory\>  </dt>
 <dd>The directory to write the log file. Defaults to `~/hawqAdminLogs`.</dd>

 <dt>-q, -\\\-quiet (no screen output)  </dt>
 <dd>Run in quiet mode. Command output is not displayed on the screen, but is still written to the log file.</dd>

 <dt>-v, -\\\-verbose  </dt>
 <dd>Displays detailed status, progress and error messages and writes them to the log files.</dd>

 <dt>-t, -\\\-timeout  </dt>
 <dd>Sets timeout value in seconds. The default is 60 seconds.</dd>

 <dt>-n, -\\\-no-update  </dt>
 <dd>Resync the standby with the master, but do not update system catalog tables.</dd>

 <dt>-\\\-locale=\<locale\>   </dt>
 <dd>Sets the default locale used by HAWQ. If not specified, the `LC_ALL`, `LC_COLLATE`, or `LANG` environment variable of the master host determines the locale. If these are not set, the default locale is `C` (`POSIX`). A locale identifier consists of a language identifier and a region identifier, and optionally a character set encoding. For example, `sv_SE` is Swedish as spoken in Sweden, `en_US` is U.S. English, and `fr_CA` is French Canadian. If more than one character set can be useful for a locale, then the specifications look like this: `en_US.UTF-8` (locale specification and character set encoding). On most systems, the command `locale` will show the locale environment settings and `locale -a` will show a list of all available locales.</dd>

 <dt>-\\\-lc-collate=\<locale\>  </dt>
 <dd>Similar to `--locale`, but sets the locale used for collation (sorting data). The sort order cannot be changed after HAWQ is initialized, so it is important to choose a collation locale that is compatible with the character set encodings that you plan to use for your data. There is a special collation name of `C` or `POSIX` (byte-order sorting as opposed to dictionary-order sorting). The `C` collation can be used with any character encoding.</dd>

 <dt>-\\\-lc-ctype=\<locale\>  </dt>
 <dd>Similar to `--locale`, but sets the locale used for character classification (what character sequences are valid and how they are interpreted). This cannot be changed after HAWQ is initialized, so it is important to choose a character classification locale that is compatible with the data you plan to store in HAWQ.</dd>

 <dt>-\\\-lc-messages=\<locale\>  </dt>
 <dd>Similar to `--locale`, but sets the locale used for messages output by HAWQ. The current version of HAWQ does not support multiple locales for output messages (all messages are in English), so changing this setting will not have any effect.</dd>

 <dt>-\\\-lc-monetary=\<locale\>  </dt>
 <dd>Similar to `--locale`, but sets the locale used for formatting currency amounts.</dd>

 <dt>-\\\-lc-numeric=\<locale\>  </dt>
 <dd>Similar to `--locale`, but sets the locale used for formatting numbers.</dd>

 <dt>-\\\-lc-time=\<locale\>  </dt>
 <dd>Similar to `--locale`, but sets the locale used for formatting dates and times.</dd>

 <dt>-\\\-bucket\_number=\<number\>   </dt>
 <dd>Sets value of `default_hash_table_bucket_number`, which sets the default number of hash buckets for creating virtual segments. This parameter overrides the default value of `default_hash_table_bucket_number` set in `hawq-site.xml` by an Ambari install. If not specified, `hawq init` will use the value in `hawq-site.xml`.</dd>

 <dt>-\\\-max\_connections=\<number\>   </dt>
 <dd>Sets the number of client connections allowed to the master. The default is 1280. Segment connections can be modified at a later time. For more information, see [Configuring Client Authentication](../../../clientaccess/client_auth.html).</dd>

 <dt>-\\\-shared\_buffers \<number\>  </dt>
 <dd>Sets the number of shared\_buffers to be used when initializing HAWQ.</dd>

 <dt>-s, -\\\-standby-host \<name\_of\_standby\_host\>  </dt>
 <dd>Adds a standby host name to hawq-site.xml and syncs it to all the nodes. If a standby host name was already defined in hawq-site.xml, using this option will overwrite the existing value.</dd>

 <dt>-?, -\\\-help  </dt>
 <dd>Displays the online help.</dd>

 ## <a id="topic1__section6"></a>Examples

 Initialize a HAWQ array with an optional standby master host:

 ``` shell
 $ hawq init standby
 ```
	---
	title: hawq init
	---

	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	The `hawq init cluster` command initializes a HAWQ system and starts it.

	Use the `hawq init master` and `hawq init segment` commands to individually initialize the master or segment nodes, respectively. Specify any format options at this time. The `hawq init standby` command initializes a standby master host for a HAWQ system.

	Use the `hawq init <object> --standby-host` option to define the host for a standby at initialization.

	## <a id="topic1__section2"></a>Synopsis

	``` pre
	hawq init <object> [--options]

	hawq init standby \| cluster
	[--standby-host <address_of_standby_host>]
	[<options>]

	hawq init -? \| --help
	```
	where:

	``` pre
	<object> = cluster \| master \| segment \| standby

	<options> =
	[-a] [-l <logfile_directory>] [-q] [-v] [-t]
	[-n]
	[--locale=<locale>] [--lc-collate=<locale>]
	[--lc-ctype=<locale>] [--lc-messages=<locale>]
	[--lc-monetary=<locale>] [--lc-numeric=<locale>]
	[--lc-time=<locale>]
	[--bucket_number <number>]
	[--max_connections <number>]
	[--shared_buffers <number>]
	```

	## <a id="topic1__section3"></a>Description

	The `hawq init <object>` utility creates a HAWQ instance using configuration parameters defined in `$GPHOME/etc/hawq-site.xml`. Before running this utility, verify that you have installed the HAWQ software on all the hosts in the array.

	In a HAWQ DBMS, each database instance (the master and all segments) must be initialized across all of the hosts in the system in a way that allows them to work together as a unified DBMS. The `hawq init cluster` utility initializes the HAWQ master and each segment instance, and configures the system as a whole. When `hawq init cluster` is run, the cluster comes online automatically without needing to explicitly start it. You can start a single node cluster without any user-defined changes to the default `hawq-site.xml` file. For larger clusters, use the template-hawq-site.xml file to specify the configuration.

	To use the template for initializing a new cluster configuration, replace the items contained within the % markers. For example, replace `value%master.host%value` and `%master.host%` 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:

	```shell
	$ hawq init cluster
	```

	This utility performs the following tasks:

	- Verifies that the parameters in the configuration file are correct.
	- Ensures that a connection can be established to each host address. If a host address cannot be reached, the utility will exit.
	- Verifies the locale settings.
	- Initializes the master instance.
	- Initializes the standby master instance (if specified).
	- Initializes the segment instances.
	- Configures the HAWQ system and checks for errors.
	- Starts the HAWQ system.

	The `hawq init standby` utility can be run on either the currently active primary master host or on the standby node.

	`hawq init standby` performs the following steps:

	- Updates the HAWQ system catalog to add the new standby master host information
	- Edits the `pg_hba.conf` file of the HAWQ master to allow access from the newly added standby master.
	- Sets up the standby master instance on the alternate master host
	- Starts the synchronization process

	A backup, standby master host serves as a 'warm standby' in the event of the primary master host becoming non-operational. The standby master is kept up to date by transaction log replication processes (the `walsender` and `walreceiver`), which run on the primary master and standby master hosts and keep the data between the primary and standby master hosts synchronized. To add a standby master to the system, use the command `hawq init standby`, for example: `init standby host09`. To configure the standby hostname at initialization without needing to run hawq config by defining it, use the --standby-host option. To create the standby above, you would specify `hawq init standby --standby-host=host09` or `hawq init cluster --standby-host=host09`.

	If the primary master fails, the log replication process is shut down. Run the `hawq activate standby` utility to activate the standby master in its place; upon activation of the standby master, the replicated logs are used to reconstruct the state of the master host at the time of the last successfully committed transaction.

	## Objects

	<dt>cluster </dt>
	<dd>Start a HAWQ cluster.</dd>

	<dt>master </dt>
	<dd>Start HAWQ master.</dd>

	<dt>segment </dt>
	<dd>Start a local segment node.</dd>

	<dt>standby </dt>
	<dd>Start a HAWQ standby master.</dd>

	## <a id="topic1__section4"></a>Options

	<dt>-a, (do not prompt) </dt>
	<dd>Do not prompt the user for confirmation.</dd>


	<dt>-l, -\\\-logdir \<logfile\_directory\> </dt>
	<dd>The directory to write the log file. Defaults to `~/hawqAdminLogs`.</dd>

	<dt>-q, -\\\-quiet (no screen output) </dt>
	<dd>Run in quiet mode. Command output is not displayed on the screen, but is still written to the log file.</dd>

	<dt>-v, -\\\-verbose </dt>
	<dd>Displays detailed status, progress and error messages and writes them to the log files.</dd>

	<dt>-t, -\\\-timeout </dt>
	<dd>Sets timeout value in seconds. The default is 60 seconds.</dd>

	<dt>-n, -\\\-no-update </dt>
	<dd>Resync the standby with the master, but do not update system catalog tables.</dd>

	<dt>-\\\-locale=\<locale\> </dt>
	<dd>Sets the default locale used by HAWQ. If not specified, the `LC_ALL`, `LC_COLLATE`, or `LANG` environment variable of the master host determines the locale. If these are not set, the default locale is `C` (`POSIX`). A locale identifier consists of a language identifier and a region identifier, and optionally a character set encoding. For example, `sv_SE` is Swedish as spoken in Sweden, `en_US` is U.S. English, and `fr_CA` is French Canadian. If more than one character set can be useful for a locale, then the specifications look like this: `en_US.UTF-8` (locale specification and character set encoding). On most systems, the command `locale` will show the locale environment settings and `locale -a` will show a list of all available locales.</dd>

	<dt>-\\\-lc-collate=\<locale\> </dt>
	<dd>Similar to `--locale`, but sets the locale used for collation (sorting data). The sort order cannot be changed after HAWQ is initialized, so it is important to choose a collation locale that is compatible with the character set encodings that you plan to use for your data. There is a special collation name of `C` or `POSIX` (byte-order sorting as opposed to dictionary-order sorting). The `C` collation can be used with any character encoding.</dd>

	<dt>-\\\-lc-ctype=\<locale\> </dt>
	<dd>Similar to `--locale`, but sets the locale used for character classification (what character sequences are valid and how they are interpreted). This cannot be changed after HAWQ is initialized, so it is important to choose a character classification locale that is compatible with the data you plan to store in HAWQ.</dd>

	<dt>-\\\-lc-messages=\<locale\> </dt>
	<dd>Similar to `--locale`, but sets the locale used for messages output by HAWQ. The current version of HAWQ does not support multiple locales for output messages (all messages are in English), so changing this setting will not have any effect.</dd>

	<dt>-\\\-lc-monetary=\<locale\> </dt>
	<dd>Similar to `--locale`, but sets the locale used for formatting currency amounts.</dd>

	<dt>-\\\-lc-numeric=\<locale\> </dt>
	<dd>Similar to `--locale`, but sets the locale used for formatting numbers.</dd>

	<dt>-\\\-lc-time=\<locale\> </dt>
	<dd>Similar to `--locale`, but sets the locale used for formatting dates and times.</dd>

	<dt>-\\\-bucket\_number=\<number\> </dt>
	<dd>Sets value of `default_hash_table_bucket_number`, which sets the default number of hash buckets for creating virtual segments. This parameter overrides the default value of `default_hash_table_bucket_number` set in `hawq-site.xml` by an Ambari install. If not specified, `hawq init` will use the value in `hawq-site.xml`.</dd>

	<dt>-\\\-max\_connections=\<number\> </dt>
	<dd>Sets the number of client connections allowed to the master. The default is 1280. Segment connections can be modified at a later time. For more information, see [Configuring Client Authentication](../../../clientaccess/client_auth.html).</dd>

	<dt>-\\\-shared\_buffers \<number\> </dt>
	<dd>Sets the number of shared\_buffers to be used when initializing HAWQ.</dd>

	<dt>-s, -\\\-standby-host \<name\_of\_standby\_host\> </dt>
	<dd>Adds a standby host name to hawq-site.xml and syncs it to all the nodes. If a standby host name was already defined in hawq-site.xml, using this option will overwrite the existing value.</dd>

	<dt>-?, -\\\-help </dt>
	<dd>Displays the online help.</dd>

	## <a id="topic1__section6"></a>Examples

	Initialize a HAWQ array with an optional standby master host:

	``` shell
	$ hawq init standby
	```