Deploying a Cluster

This section outlines all the steps required to have a complete cluster running. Before commencing, ensure you have completed all of the Prerequisites outlined in "Prerequisites" and you have downloaded and unpacked the deployment package (See "Deployment Sources")

Configure passwords

Before we start, you will need to set the relevant access passwords. An example file has been provided which you should copy and then update accordingly.

• Copy the example file:

shell> cd /opt/continuent/software/tungsten-clustering-9.0.0-1
shell> cd ansible/
shell> cp group_vars/all/vault.yml.example group_vars/all/vault.yml

• Edit the file using your chosen editor, such as vi, and change every occurrence of CHANGE_ME with a strong password of your choice
• Encrypt the file, entering a password of your choice when prompted:

shell> ansible-vault encrypt group_vars/all/vault.yml

• Save the vault password you selected so that the ansible deployment can read it (This should be created within the ansible directory):

shell> set unmask 0777
shell> printf '%s' 'your-vault-password' > .vault_pass
shell> chmod 600 .vault_pass

Configure hosts

You will need to supply the hostnames for ansible to deploy to. The hosts should be configured as per the "Prerequisites" and also be reachable from the staging host to allow ansible to deploy and configure the cluster.

• Copy the example file:

shell> cd /opt/continuent/software/tungsten-clustering-9.0.0-1
shell> cd ansible/
shell> cp inventory/hosts.ini.example inventory/hosts.ini

• Edit the file using your chosen editor, such as vi, and add your hostnames under the correct section, for example the below file is updated for a 3-node cluster built in AWS:

shell> vim inventory/hosts.ini

[db_servers]
db1 ansible_host=db1.yourdomain.com
db2 ansible_host=db2.yourdomain.com
db3 ansible_host=db3.yourdomain.com

[witness]

[servers:children]
db_servers
witness

[all:vars]
ansible_user=root
ansible_ssh_private_key_file=~/.ssh/id_ed25519
ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'

• If you wish to use an Active Witness in place of a full database node, the configuration would look something like the following:

shell> vim inventory/hosts.ini

[db_servers]
db1 ansible_host=db1.yourdomain.com
db2 ansible_host=db2.yourdomain.com

[witness]
db3 ansible_host=db3.yourdomain.com

[servers:children]
db_servers
witness

[all:vars]
ansible_user=tungsten
ansible_ssh_private_key_file=~/.ssh/id_ed25519
ansible_ssh_common_args='-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null'

Deploy the cluster

When you have configured the passwords and the hosts you are now ready to start the Ansible deployment. This will connect to each host and:

• Configure OS user accounts for Tungsten
• Configure the relevant files for connectivity between hosts
• Configure cluster properties
• Deploy the Tungsten software package
• Install Postgres and other dependencies such as Java, Perl and Ruby
• Install Tungsten Clustering for PostgreSQL
• Start the software

There are additional options that you can supply to ansible, these are outlined in the tables below:

Core options

Click to filter entries by Product:

Option	Description	Product	Version
db_type	Configure which database type to deploy. Default: postgresql | Valid: mysql, postgresql	CTPG	9.0.0
install_java	Should Java be installed on the cluster nodes. Default: true | Valid: true, false	CTPG	9.0.0
install_tungsten	Should the tungsten software be installed. Default: true | Valid: true, false	CTPG	9.0.0

PostgreSQL Specific Options

Click to filter entries by Product:

Option	Description	Product	Version
pg_dbname	The default PostgreSQL database. This will also be created by ansible during deployment. Default: testing	CTPG	9.0.0
pg_port	Which port should PostgreSQL be configured to run on. Default: 15432	CTPG	9.0.0
pg_version	Which version of PostgreSQL should be installed. Default: 18 | Valid: 16, 17, 18	CTPG	9.0.0

Other Miscellaneous Options

Click to filter entries by Product:

Option	Description	Product	Version
java_version	Which version of Java should be installed. Default: 11 | Valid: 8, 11, 17, 21	CTPG	9.0.0
service_name	Set the service name for the cluster. Default: alpha	CTPG	9.0.0
topology	Set the topology for the deployment. In the BETA release, "std-3" is the only valid option. Default: std-3 | Valid: std-3, std-2+1w	CTPG	9.0.0

Tungsten Properties

Customers that are familiar with Tungsten Clustering for MySQL will be familiar with the process of configuring custom cluster properties via the /etc/tungsten/tungsten.ini.

With the first BETA release of Tungsten Clustering for PostgreSQL it is possible to only set specific values within the included INI template file. The default /etc/tungsten/tungsten.ini equivalent is as follows, assuming no override properties have been supplied:

Example tungsten.ini

[defaults]
user=tungsten
install-directory=/opt/continuent
replication-user=tungsten
replication-password=secret
replication-port=15432
application-user=app_user
application-password=secret
application-port=5432
connector-listen-port=5432
conn-java-mem-size=256
mgr-java-mem-size=256
repl-java-mem-size=1024
property=forcedDBforUnspecConnections=testing
connector-db-protocol=postgresql
enable-connector-bridge-mode=false
disable-security-controls=true
replicator-rest-api-address=127.0.0.1
replicator-rest-api-authentication=true
manager-rest-api-address=127.0.0.1
manager-rest-api-authentication=true
manager-rest-api-full-access=false
connector-rest-api-address=127.0.0.1
connector-rest-api-authentication=true
start-and-report=true
repl-datasource-jdbcvendor=postgresql
repl-datasource-jdbcdriver=org.postgresql.Driver
repl-datasource-jdbcscheme=jdbc:postgresql://

[alpha]
topology=clustered
members=db1,db2,db3
connectors=db1,db2,db3
master=db1
datasource-type=postgresql
repl-postgresql-dbname=testing

Show argument definitions

user=tungstenOS System User, for example tungsten. DO NOT use root.

▸install-directory=/opt/continuentInstallation directory.

replication-user=tungstenUser for database connection.

▸replication-password=secretDatabase password.

▸replication-port=15432Database network port.

application-user=app_userDatabase username for the connector.

application-password=secretDatabase password for the connector.

application-port=5432Port for the connector to listen on.

connector-listen-port=5432Port for the connector to listen on.

▸conn-java-mem-size=256Connector Java heap memory size used to buffer data between clients and databases.

mgr-java-mem-size=256Manager Java heap memory size in Mb (min 128)

repl-java-mem-size=1024Replicator Java heap memory size in Mb (min 128)

property=forcedDBforUnspecConnections=testingNo description available

connector-db-protocol=postgresqlNo description available

enable-connector-bridge-mode=falseEnable the Tungsten Connector bridge mode.

▸disable-security-controls=trueDisables all forms of security, including SSL, TLS and authentication.

replicator-rest-api-address=127.0.0.1Address for the API to bind too.Available from v7.0.0

replicator-rest-api-authentication=trueEnforce authentication for the API.Available from v7.0.0

manager-rest-api-address=127.0.0.1Address for the API to bind too.Available from v7.0.0

manager-rest-api-authentication=trueEnforce authentication for the API.Available from v7.0.0

manager-rest-api-full-access=falseNo description available

connector-rest-api-address=127.0.0.1Address for the API to bind too.Available from v7.0.0

connector-rest-api-authentication=trueEnforce authentication for the API.Available from v7.0.0

▸start-and-report=trueStart the services and report out the status after configuration.

repl-datasource-jdbcvendor=postgresqlNo description available

repl-datasource-jdbcdriver=org.postgresql.DriverNo description available

repl-datasource-jdbcscheme=jdbc:postgresql://No description available

The following overrides are available and should be supplied on the Ansible deployment command-line, as shown in the examples below:

Tungsten Specific Options

Click to filter entries by Product:

Option	Description	Product	Version
application_port Aliases: connector_listen_port	Set the Port that the connectors are running on. Defaults to 3306 for MySQL and 5432 for PostgreSQL. Maps to application-port	CTPG	9.0.0
application_user	Set the default user for the connectors. Maps to application-user Default: app_user	CTPG	9.0.0
conn_java_mem_size	Set the memory for the Connector process. Maps to conn-java-mem-size Default: 256	CTPG	9.0.0
connector_rest_api_address	Set the address for the API to bind too. Maps to connector-rest-api-address Default: 127.0.0.1	CTPG	9.0.0
connector_rest_api_authentication	Enforces authentication for the Connector API. Maps to connector-rest-api-authentication Default: true | Valid: true, false	CTPG	9.0.0
continuent_root	Set the installation path for Tungsten Software. Maps to install-directory Default: /opt/continuent	CTPG	9.0.0
manager_rest_api_address	Set the address for the API to bind too. Maps to manager-rest-api-address Default: 127.0.0.1	CTPG	9.0.0
manager_rest_api_authentication	Enforces authentication for the Manager API. Maps to manager-rest-api-authentication Default: true | Valid: true, false	CTPG	9.0.0
mgr_java_mem_size	Set the memory for the Manager process. Maps to mgr-java-mem-size Default: 250	CTPG	9.0.0
repl_java_mem_size	Set the memory for the Replicator processes. Maps to repl-java-mem-size Default: 1024	CTPG	9.0.0
replication_port	Set the Port that the datases are running on. Defaults to 13306 for MySQL and 15432 for PostgreSQL. Maps to replication-port	CTPG	9.0.0
replication_user	Set the user for the replicator. Maps to replication-user Default: tungsten	CTPG	9.0.0
replicator_rest_api_address	Set the address for the API to bind too. Maps to replicator-rest-api-address Default: 127.0.0.1	CTPG	9.0.0
replicator_rest_api_authentication	Enforces authentication for the Replicator API. Maps to replicator-rest-api-authentication Default: true | Valid: true, false	CTPG	9.0.0
security	Should security options be enabled within Tungsten. Maps to disable-security-controls Default: true | Valid: true, false	CTPG	9.0.0
system_user	Set the OS System user. Do NOT use root. Maps to user Default: tungsten	CTPG	9.0.0

To deploy the cluster with default settings, execute the following command:

shell> cd /opt/continuent/software/tungsten-clustering-9.0.0-1/ansible
shell> ansible-playbook -i inventory/hosts.ini site.yml \
--vault-password-file .vault_pass

or, should you wish to change any specific options:

shell> cd /opt/continuent/software/tungsten-clustering-9.0.0-1/ansible
shell> ansible-playbook -i inventory/hosts.ini site.yml \
-e "db_type=postgresql pg_dbname=mydb repl_java_mem_size=2048" \
--vault-password-file .vault_pass

Once the ansible scripts have completed, you should now be able to connect to your hosts and manage your cluster.

Review the following documentation sections for information on the command line tools available to manage the cluster:

• "The cctrl Command" - for managing the cluster, switching primary nodes etc
• "The trepctl Command" - for managing the replicators
• "The THL Command" - for working with the THL files

Connecting to the databases

When you have a running cluster, there are a few different ways in which you can connect to the databases. First establish a connection to the host, and then you can issue any of the following options:

• connector sql - This will connect to the database via the connector
• connector sql bypass - This will connect directly to the local database on the host that you are connected to.
• Using native cmdline tools, such as psql or mysql

Native cli tools

To use the native cli commands you must ensure you specify the ports correctly depending upon whether you wish to connect via the connector, or directly to the database

For example

• to connect to the local PostgreSQL database (The same as issuing connector sql bypass):

Warning

Be VERY careful when connecting and issuing SQL directly to the database. Any changes written in error to a replica will not replicate to the primary resulting in data drift. Additionally, if you require DDL changes to replicate, these MUST be applied to the primary via the connector. DDL written directly to a primary database bypassing the connector will not replicate.

shell> psql --user=your_user --port=15432 
or
shell> psql -U your_user -W -p 15432

Warning

VACUUM, VACUUM FULL, VACUUM ANALYZE, CLUSTER, ANALYZE and REINDEX do not replicate and must be run per node against the local database. See "DDL and Replication"

• to connect to the PostgreSQL database via the connector (The same as issuing connector sql):

shell> psql --user=your_user --port=5432 --host=db1 
or
shell> psql -U your_user -W -p 5432 -h db1

Note

The hostname must be supplied when connecting via the connector.

Note

The behavior may differ if you have optionally chosen to alter the pg_hba.conf configuration