Postgres-XC Wiki

What is in this page?[]

This page describes how to configure very small Postgres-XC cluster in you laptop, with about 2GB of memory available. You need to run some 64bit Linux on you Laptop or virtual machine (for example, Virtualbox). 32bit Linux will be okay too.

What we are configuring[]

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

  1. one GTM: you need only one GTM
  2. two coordinators: you can see each coordinator provides the same database view to your application, including psql.
  3. two datanodes: you can find how Postgres-XC tables are replicated and distributed.

What you need to determine[]

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

  1. User
    You should determine the owner of Postgres-XC cluster (Linux user). Here, postgresxc is your Postgres-XC database cluster owner and its home directory is /home/postgresxc.
  2. 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. Coordinator: /home/postgresxc/pgxc/coord1, /home/postgresxc/pgxc/coord2 (recall we're configuring two coordinators)
    3. Datanode: /home/postgresxc/pgxc/datanode1, /home/postgresxc/pgxc/datanode2 (again, we're configuring two datanodes).
  3. Node name
    Each node needs unique node name. Let's assign the following names.
    1. GTM: gtm
    2. Cordinators: coord1 and coord2
    3. Datanode: datanode1 and datanode2
  4. 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 runs in single server (or virtual machine), you need to assign different port number to each of them. Here, we assume:
    1. GTM: 20001,
    2. Coordinators: 20004 and 2005 for coord1 and coord2 respectively,
    3. Datanodes: 20006 and 20007 respectively.

Each component has similar set of resources you should assign.

Configuring each component[]

Now you're ready to configure each component. Because /home/postgresxc/pgxc is the common directory to start with, let's create this directory first.

$ cd /home/postgresxc
$ mkdir pgxc

Then, please visit pages for each component as follows:

  1. Configure GTM
  2. Configure Coordinators
  3. Configure Datanode

Now you're ready to start you Postgres-XC cluster.

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.

$ gtm_ctl start -Z gtm -D /home/postgresxc/pgxc/gtm

Next, you start coordinators and datanodes. You can start them in the order you like, but it is a good practice to start datanode first. If you start coordinator first and your applications issue SQL statement before datanodes start, it will lead to an error.

So you do like:

$ pg_ctl start -Z datanode -D /home/postgresxc/pgxc/datanode1 -o "-i"
$ pg_ctl start -Z datanode -D /home/postgresxc/pgxc/datanode2 -o "-i"
$ pg_ctl start -Z coordinator -D /home/postgresxc/pgxc/coord1 -o "-i"
$ pg_ctl start -Z coordinator -D /home/postgresxc/pgxc/coord2 -o "-i"

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

Before beginning your work[]

Please note that until know, 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 psotgresxc, you're the superuser.

First, you configure coord1.

$ psql -p 20004 postgres
# create node coord2 with (type = 'coordinator', host = 'localhost', port = 20005);
# create node datanode1 with (type = 'datanode', host = 'localhost', port = 20006);
# create node datanode2 with (type = 'datanode', host = 'localhost', port = 20007);
# \q

Then, do the similar thing for coord2.

$ psql -p 20005 postgres
# create node coord1 with (type = 'coordinator', host = 'localhost', port = 20004);
# create node datanode1 with (type = 'datanode', host = 'localhost', port = 20006);
# create node datanode2 with (type = 'datanode', host = 'localhost', port = 20007);
# \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.

Stopping your Postgres-XC cluster[]

You should not stop GTM while other components are running. As described in starting the cluster, it is a good habit to stop coordinator fist, then datanode and gtm. When you stop coordinator, they may hold connections to other coordinators and datanodes. To shutdown cluster calmly, you should close such internal connections.

$ psql -p 30004 'CLEAN CONNECTION TO ALL FOR DATABASE postgres' postgres
$ psql -p 30005 'CLEAN CONNECTION TO ALL FOR DATABASE postgres' postgres

Please note that you should clean connection for other databases if you're using them. Then you can stop each component as follows:

$ pg_ctl stop -Z coordinator -D /home/postgresxc/pgxc/coord1
$ pg_ctl stop -Z coordinator -D /home/postgresxc/pgxc/coord2
$ pg_ctl stop -Z datanode -D /home/postgresxc/pgxc/datanode1
$ pg_ctl stop -Z datanode -D /home/postgresxc/pgxc/datanode2
$ gtm_ctl stop -Z gtm -D /home/postgresxc/pgxc/gtm