Creating your first cluster
===========================

Create a local cluster using Docker Compose to get familiar with the EDB
Postgres Distributed (PGD) 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, use the Docker Compose file provided
by EDB to set up a local cluster with three nodes.

1. Make sure you have Docker and Docker Compose installed on your local
   machine. You can follow the `Docker installation guide <https://docs.docker.com/get-docker/>`_  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:

.. code:: bash

     mkdir pgd-cluster
     cd pgd-cluster

3. Download the PGD Docker Compose file:

.. code:: bash

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

The command downloads the PGD Docker Quickstart kit, which includes the
Docker Compose file and other necessary files to get started with PGD.

4. Once the download is complete, prepare the environment for the PGD
   cluster.

.. code:: bash

     ./qs.sh prepare

The command creates the necessary directories and files for the PGD
cluster.

5. Build the Docker images for the PGD cluster:

.. code:: bash

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

The command builds the Docker image needed for the PGD Quickstart
cluster.

6. After the images are built, start the PGD cluster :

.. code:: bash

     ./qs.sh start

The command starts the Docker containers and creates a local cluster
with the default configuration.

Accessing the PGD Cluster
-------------------------

1. Once the containers are up and running, access the PGD cluster:

.. code:: bash

     docker compose exec host-1 psql pgddb

The command connects to the first node of the cluster using the ``psql``
command-line interface.

Connect to the database via the first node for maintenance and
management tasks.

1. For application and user access, you connect using Connection Manager
   which, by default, is running on TCP port 6432 of all the hosts in
   the cluster. Connect to the write leader node in the cluster using
   the following command:

.. code:: bash

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

Replace ``-h host-1`` with the name of any host in the cluster, as they
all run Connection Manager.

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

.. code:: bash

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

The command 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.

.. code:: sql

     select node_name from bdr.local_node_summary;
     __OUTPUT__
       node_name
       -----------
       node-1
       (1 row)

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

.. code:: bash

     docker compose exec host-1 pgd nodes list 
     __OUTPUT__
     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

The command lists the nodes in the cluster and their status.

1. Alternatively, open a shell on the host-1 container and run the pgd
   command directly:

.. code:: bash

     docker compose exec host-1 bash
     pgd nodes list
     __OUTPUT__
     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

The command gives you access to the PGD CLI and allows you to run any
PGD commands directly on the host-1 container.

Next Steps
----------

- :ref:`Working with SQL and the PGD cluster <Working with SQL and the PGD cluster>`  to understand how to connect and interact with the
  cluster using SQL commands.

- :ref:`Loading data into your PGD Cluster <Loading data into your PGD Cluster>`  into the cluster using the ``COPY`` command or
  ``pg_dump`` and ``pg_restore`` .

- :ref:`Using PGD CLI <Using PGD CLI>`  to monitor and manage the cluster.