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

This guide helps you create a local cluster using Docker Compose. This
is a great way 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, 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 <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. Run the following command to download the PGD Docker Compose file:

.. code:: bash

      curl -L https://enterprisedb.com/docs/pgd/latest/overview/quickstart/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:

.. code:: bash

     ./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:

.. code:: bash

     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:

.. code:: bash

     ./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:

.. code:: bash

     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.

1. You can 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

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:

.. code:: bash

     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.

.. code:: bash

     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:

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

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:

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

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:

- :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.