What is in this page?

This page describes how to configure small Postgres-XC cluster using three servers. Each server should run 64bit Linux (32bit may work though) and should be connected via appropriate TCP/IP connection each other. In this page, we assume each server's name as node01, node02 and node03.

What we are configuring

We're configuring the following Postgres-XC components. If you are not familiar with them, please go back to the page Configuration.

  1. one GTM: you need only one GTM.
  2. two GTM proxies: it is recommended to configure GTM proxies for each server to improve the performance.
  3. two coordinators: you can see each coordinator provides the same database view to your application including psql.
  4. two datanodes: you can find how Postgres-XC tables are replicated and distributed.

What you need to determine

You should determine the followng resources for each of the component above:

  1. User
    You should determine the owner of Postgres-XC user (Linux user). Here, postgresxc is your Postgres-XC database cluster owner. It is highly recommended to use the same user in all the servers. Postgresxc's home directory is /home/postgresxc in all the servers above.
  2. Which server to configure what
    We should determine what components should be configured in which server. It is a good start to install a pair of coordinator and datanode in servers. Here, we assume the following.
    1. GTM: configured in node03
    2. GTM proxies: configured in node01 and node02
    3. Coordinators: configured in node01 and node02
    4. Datanodes: configured in node01 and node02
  3. Working directory
    Each of the components needs separate working directory where various local information is stored. Let's assume the following working directory.
    1. GTM: /home/postgresxc/pgxc/gtm
    2. GTM proxy: /home/postgresxc/pgxc/gtm_proxy
    3. Coordinator: /home/postgresxc/pgxc/coord (recall we should configure coordinators both in node 01 and node02)
    4. Datanode: /home/postgresxc/pgxc/datanode (recall we should configure datanodes both in node01 and node02)
  4. Node name
    Each node needs unique node name. Let's assign the following names.
    1. GTM: gtm
    2. GTM proxies: gtm_pxy01 and gtm_pxy02 (on node01 and node02 respectively)
    3. Cordinators: coord1 and coord2 (on node01 and node02 respectively)
    4. Datanodes: datanode1 and datanode2 (on node01 and node02 respecitively)
  5. Port number
    Each component interact each other, as well as with applications. They need unique TCP/IP port for this purpose. Because all the components run on single server (or virtual machine), you need to assign different port number to each of them. Here, we assume:
    1. GTM: 20001
    2. GTM proxies: 20001
    3. Coordinators: 20004
    4. Datanodes: 20006

Each component has similar set of resources you should assign.

Configuring each component

Now we begin the configuration from a server 'main'. Because you need to login to different servers, the command prompts are prefixed with the server name such as:

[main]$ ssh node01

Now, please visit pages for each compoent as follows:

  1. Configure Server GTM
  2. Configure Server GTM Proxies
  3. Configure Server Coordinators
  4. Configure Server Datanodes

Now your're ready to run your applications.

Starting your Postgres-XC cluster

You have done all the configurations successfully. Congratulations!! Now you can start your Postgres-XC cluster by starting each component one by one. You should start GTM first because all the other components assume that GTM is running. Then you start GTM Proxy.

Please do like this.

[main]$ ssh node03
[node03]$ gtm_ctl start -Z gtm -D /home/postgresxc/pgxc/gtm
[node03]$ exit
[main]$ ssh node01
[node01]$ gtm_ctl start -Z gtm_proxy -D /home/postgresxc/pgxc/gtm_proxy
[node01]$ exit
[main]$ ssh node02
[node02]$ gtm_ctl start -Z gtm_proxy -D /home/postgresxc/pgxc/gtm_proxy
[node02]$ exit

Now you can start coordinator and datanode. Although you can start them in arbitrary order, it is a good habit to start datanode first. If you start coordinator first and your applications issue SQL statements before datanodes start, it will lead to an error.

You can do like this:

[main]$ ssh node01
[node01]$ pg_ctl start -Z datanode -D /home/postgresxc/pgxc/datanode
[node01]$ exit
[main]$ ssh node02
[node02]$ pg_ctl start -Z datanode -D /home/postgresxc/pgxc/datanode
[node02]$ exit
[main]$ ssh node01
[node01]$ pg_ctl start -Z coordinator -D /home/postgresxc/pgxc/coordinator
[node01]$ exit
[main]$ ssh node02
[node02]$ pg_ctl start -Z coordinator -D /home/postgresxc/pgxc/coordinator
[node02]$ exit

All the components are up and waiting for your application to connect.

Before beginning your work

Please note that until now, we told each component where GTM is. However, coordinators do not know where other coordinators are and where datanodes are. They're very important configuration and you should configure them here.

Only coordinators need to know other nodes. Here, we use psql for this purpose and use CREATE NODE and ALTER NODE statement. At this moment, database called 'postgres' is available. So login to postgres. Because you created the database as user name postgresxc, you're the superuser.

First, you configure coord1.

[main]$ psql -p 20004 -h node01 postgres
# CREATE NODE coord2 WITH (TYPE = 'coordinator', HOST = 'node02', PORT = 20004);
# CREATE NODE datanode1 WITH (TYPE = 'datanode', HOST = 'node01', PORT = 20006);
# CREATE NODE datanode2 WITH (TYPE = 'datanode', HOST = 'node02', PORT = 20006);
# \q

Next, do the similar for coord2.

[main]$ psql -p 20004 -h node02 postgres
# CREATE NODE coord1 WITH (TYPE = 'coordinator', HOST = 'node01', PORT = 20004);
# CREATE NODE datanode1 WITH (TYPE = 'datanode', HOST = 'node01', PORT = 20006);
# CREATE NODE datanode2 WITH (TYPE = 'datanode', HOST = 'node02', PORT = 20006);
# \q

You must do the above only at the first time you started Postgres-XC cluster. After then, you skip this process and connect your application to any of the coordinators.

Community content is available under CC-BY-SA unless otherwise noted.