Creating your first cluster (PGD Essential) v6.0.1

This part of the Getting Started guide will help you create a local cluster using Docker Compose. This is a great way to get familiar with the EDB Postgres Distributed (PGD) Essential features and functionality.

Prerequisites

• Docker and Docker Compose installed on your local machine.

Install the PGD Docker Quickstart kit

To create your first PGD cluster, you can use the Docker Compose file provided by EDB. This will set up a local cluster with three nodes, which is perfect for testing and development purposes.

1. Make sure you have Docker and Docker Compose installed on your local machine. You can follow the Docker installation guide if you haven't done so already.

2. Open a terminal and on the machine where you have docker installed, create a new directory for your PGD cluster, for example:

   → WrapCopy

   mkdir pgd-cluster
   cd pgd-cluster

3. Run the following command to download the PGD Docker Compose file:

   → WrapCopy

    curl -L https://enterprisedb.com/docs/pgd/latest/get-started/assets/pgd_quickstart.sh | bash

   This will download the PGD Docker Quickstart kit, which includes the Docker Compose file and other necessary files to get started with PGD Essential.

4. Once the download is complete, you will need to prepare the environment for the PGD cluster. This is done by running the following command:

   → WrapCopy

   ./qs.sh prepare

   This command will create the necessary directories and files for the PGD cluster.

5. Now you have to build the Docker images for the PGD cluster. You can do this by running the following command:

   → WrapCopy

   export EDB_SUBSCRIPTION_TOKEN=...
   ./qs.sh build

   This command will build the Docker image needed for the PGD Quickstart cluster.

6. After the images are built, you can start the PGD cluster using Docker Compose. Run the following command:

   → WrapCopy

   ./qs.sh start

   This command will start the Docker containers and create a local cluster with the default configuration, running in the background.

Accessing the PGD Cluster

1. Once the containers are up and running, you can access the PGD cluster using the following command:

   → WrapCopy

   docker compose exec host-1 psql pgddb

   This command will connect you directly to the first node of the cluster using the psql command-line interface.

   This is how you would connect to the database for maintenance and management tasks.

   For application and user access you will usually connect using the connection manager which, by default, is running on TCP port 6432 of all the hosts in the cluster.

2. You can connect to the write leader node in the cluster using the following command:

   → WrapCopy

   docker compose exec host-1 psql -h host-1 -p 6432 pgddb

   You can replace -h host-1 with the name of any host in the cluster, as they all run the connection manager.

   If you have the psql client installed on your local machine, you can also connect to the cluster using the following command:

   → WrapCopy

   export PGPASSWORD=secret
   psql -h localhost -p 6432 -U postgres pgddb

   This connects to the connection manager running on the host-3 container on port 6432. This is then routed to the write leader node in the cluster.

   → WrapCopy

   pgddb=# select node_name from bdr.local_node_summary;
   node_name
   -----------
   node-1
   (1 row)

1. To use the PGD CLI from outside the containers, you can run the following command:

docker compose exec host-1 pgd nodes list 

 Node Name | Group Name | Node Kind | Join State | Node Status
-----------+------------+-----------+------------+-------------
 node-1    | group-1    | data      | ACTIVE     | Up
 node-2    | group-1    | data      | ACTIVE     | Up
 node-3    | group-1    | data      | ACTIVE     | Up

This pgd command will lists the nodes in the cluster and their status.

You can also get a shell on the host-1 container and run the pgd command directly:

docker compose exec host-1 bash
pgd nodes list

 Node Name | Group Name | Node Kind | Join State | Node Status
-----------+------------+-----------+------------+-------------
 node-1    | group-1    | data      | ACTIVE     | Up
 node-2    | group-1    | data      | ACTIVE     | Up
 node-3    | group-1    | data      | ACTIVE     | Up

This will give you access to the PGD CLI and allow you to run any PGD commands directly on the host-1 container.

Next Steps

Now that you have created your first PGD cluster, you can explore the following topics:

• Working with SQL and the cluster to understand how to connect and interact with the cluster using SQL commands.
• Loading data into the cluster using the COPY command or pg_dump and pg_restore.
• Using PGD CLI to monitor and manage the cluster.