Json - pgEdge

The Cluster Configuration File

You can use the pgedge cluster json-create command to create a .json cluster definition file that configures a replication cluster, and then deploy the cluster with the pgedge cluster-init command. The commands simplify configuration and deployment of a cluster on remote or local hosts; if you are happy with your cluster configuration, reusing the configuration file to deploy another cluster is simply a matter of modifying the cluster details and initializing another cluster with new node details. The command syntax to create a cluster_name.json file is:

./pgedge cluster json-create cluster_name db_name node_count db_superuser password --port=port_number --pg_ver=pg_version -force

When you invoke the command, specify the following values for the required arguments:

cluster_name is the name of the cluster. A directory with this same name will be created in the cluster directory; the file describing the cluster configuration will be named cluster_name.json.
db_name is the name of your PostgreSQL database.
node_count specifies the number of nodes that will be in the cluster. Nodes will be named n1, n2, n3, etc.
db_superuser specifies the username of the PostgreSQL database owner/superuser that will be created for this database.
password is the password of the database superuser.

Optionally, include:

the --port flag and the port number to assign a listener port for the PostgreSQL database.
the --pg_ver flag and the PostgreSQL version you'd like to install.
the --force flag to suppress execution of a script that will prompt you for detailed configuration information for each node.

If you do not include the --force option, when you press return, the command initiates a script that allows you to enter detailed information about each node your cluster.

[ec2-user@ip-172-31-19-133 pgedge]$ ./pgedge cluster json-create temp 2 lcdb lcusr password
PostgreSQL version ['15', '16', '17'] (default: '16'): 
Spock version ['3.3.6', '3.3.5', '4.0.10', '4.0.9', '4.0.8'] (default: '4.0.10'): 
Enable pgBackRest? (Y/N) (default: 'N'): 

Configuring Node 1
  Public IP address for Node 1 (default: '127.0.0.1'): 
  Private IP address for Node 1 (default: '127.0.0.1'): 
  PostgreSQL port for Node 1 (default: '5432'): 

Configuring Node 2
  Public IP address for Node 2 (default: '127.0.0.1'): 
  Private IP address for Node 2 (default: '127.0.0.1'): 
  PostgreSQL port for Node 2 (default: '6432'): 6432

################################################################################
# Cluster Name       : temp
# PostgreSQL Version : 16
# Spock Version      : 4.0.10
# Number of Nodes    : 2
# Database Name      : lcdb
# User               : lcusr
# pgBackRest Enabled : No
# Node 1
#    Public IP       : 127.0.0.1
#    Private IP      : 127.0.0.1
#    Port            : 5432
# Node 2
#    Public IP       : 127.0.0.1
#    Private IP      : 127.0.0.1
#    Port            : 6432
################################################################################
Do you want to save this configuration? (Y/N):

Specify Y to write the details to the cluster.json file (located in pgedge/cluster/cluster_name/cluster_name.json), or N to skip file creation. After creating the file, you can manually edit the file to correct or add any important information about the cluster.

To suppress the script execution, include the --force flag when you invoke the ./pgedge cluster json-create command; if you do not run the script, you will need to manually update the file to include any missing properties or provide node details.

Inside the Cluster Configuration File

The pgEdge Platform cluster json-create command creates a JSON file that you can modify and use to deploy a pgEdge cluster. To create the file, install the pgEdge Platform, and then navigate into the pgedge directory and invoke the following command:

./pgedge cluster json-create demo lcdb 3 lcusr 1safepassword

The command creates a file named demo.json in cluster/demo directory that describes a 3 node cluster that replicates a PostgreSQL 17 database named lcdb. The first node of the cluster (n1) is listening on port 6432; when you edit the .json file, you'll specify the port numbers that will be used by n2 and n3. The database superuser is named lcusr, and the associated password is 1safepassword.

The resulting demo.json file will look like this:

{
    "json_version": "1.0",
    "cluster_name": "demo",
    "log_level": "debug",
    "update_date": "2025-04-01 14:16:05 GMT",
    "pgedge": {
        "pg_version": "17",
        "auto_start": "off",
        "spock": {
            "spock_version": "4.0.10",
            "auto_ddl": "on"
        },
        "databases": [
            {
                "db_name": "lcdb",
                "db_user": "lcusr",
                "db_password": "1safepassword"
            }
        ]
    },
    "is_ha_cluster": false,
    "node_groups": [
        {
            "ssh": {
                "os_user": "ec2-user",
                "private_key": ""
            },
            "name": "n1",
            "is_active": "on",
            "public_ip": "127.0.0.1",
            "private_ip": "127.0.0.1",
            "port": "6432",
            "path": "/home/ec2-user/work/platform_test/nc/pgedge/cluster/demo/n1",
            "replicas": 0
        },
        {
            "ssh": {
                "os_user": "ec2-user",
                "private_key": ""
            },
            "name": "n2",
            "is_active": "on",
            "public_ip": "127.0.0.1",
            "private_ip": "127.0.0.1",
            "port": "6433",
            "path": "/home/ec2-user/work/platform_test/nc/pgedge/cluster/demo/n2",
            "replicas": 0
        },
        {
            "ssh": {
                "os_user": "ec2-user",
                "private_key": ""
            },
            "name": "n3",
            "is_active": "on",
            "public_ip": "127.0.0.1",
            "private_ip": "127.0.0.1",
            "port": "6434",
            "path": "/home/ec2-user/work/platform_test/nc/pgedge/cluster/demo/n3",
            "replicas": 0
        }
    ]
}

Cluster Configuration Properties

Properties within the cluster configuration file describe a cluster:

Property	Description
json_version	The version of the json file being used.
cluster_name	The name of the cluster.
log_level	Optional; specify `debug` to produce verbose logging.
update_date	The most recent modification date of the cluster configuration file.
pgedge -> pg_version	The installed PostgreSQL version.
pgedge -> autostart	The state of the autostart feature; accepted values are `on` and `off`.
pgedge -> spock_version	The installed version of the Spock extension.
pgedge -> auto_ddl	The state of the `auto_ddl` feature; accepted values are `on` and `off`.
pgedge -> databases -> db_name	The name of the database created during the installation.
pgedge -> databases -> db_user	The name of the database superuser created when the cluster is deployed.
pgedge -> databases -> db_password	The password used by the database superuser to connect to the database.
node_groups -> ssh -> os_user	The name of an existing non-root operating system user.
node_groups -> ssh -> private_key	The path to and name of the SSH private key file on the cluster host.
node_groups -> name	The unique name of a cluster node (default values are `n1`, `n2`, `n3`, etc.).
node_groups -> is_active	The state of the node; accepted values are `on` and `off`.
node_groups -> public_ip	The public IP address of the node. If only a public IP address is provided, it will be used for both replication and SSH connections. If a public IP address and private IP address are provided, the public address will be used for SSH connections.
node_groups -> private_ip	The private IP address of the node. If only a private IP address is provided, it will be used for both replication and SSH connections. If a public IP address and private IP address are provided, the private address will be used for replication connections.
node_groups -> port	The PostgreSQL listener port.
node_groups -> path	The complete installation path to the node's installation directory.
node_groups -> backrest -> stanza	The location of the pgBackRest stanza (configuration) file.
node_groups -> backrest -> repo1-path	The path to the pgBackRest repository.
node_groups -> backrest -> repo1-retention-full	The pgBackRest retention options.
node_groups -> backrest -> log-level-console	The pgBackRest log level setting.
node_groups -> backrest -> repo1-cipher-type	The pgBackRest cipher type.
node_groups -> backrest -> archive_mode	Specifies if pgBackRest archiving is `on` or `off`.
node_groups -> replicas	The number of read-only replica nodes.
node_groups -> sub_nodes	The configuration details for a read-only replica node.
node_groups -> sub_nodes -> ssh -> os_user	The name of an existing non-root operating system user on the sub node.
node_groups -> sub_nodes -> ssh -> private_key	The path to and name of the SSH private key file on the sub node.
node_groups -> sub_nodes -> name	The name of the sub node host.
node_groups -> sub_nodes -> is_active	The state of the sub node; the value should be `off` when acting as a supporting read-only node.
node_groups -> sub_nodes -> public_ip	The public IP address of the sub node. If only a public IP address is provided, it will be used for both replication and SSH connections. If a public IP address and private IP address are provided, the public address will be used for SSH connections.
node_groups -> sub_nodes -> private_ip	The private IP address of the sub node. If only a private IP address is provided, it will be used for both replication and SSH connections. If a public IP address and private IP address are provided, the private address will be used for replication connections.
node_groups -> sub_nodes -> port	The PostgreSQL listener port on the sub node.
node_groups -> sub_nodes -> path	The complete installation path to the sub node's installation directory.
node_groups -> sub_nodes -> backrest -> stanza	The location of the pgBackRest stanza (configuration) file on the sub node.
node_groups -> sub_nodes -> backrest -> repo1-path	The path to the pgBackRest repository on the sub node.
node_groups -> sub_nodes -> backrest -> repo1-retention-full	The pgBackRest retention options on the sub node.
node_groups -> sub_nodes -> backrest -> log-level-console	The pgBackRest log level setting on the sub node..
node_groups -> sub_nodes -> backrest -> repo1-cipher-type	The pgBackRest cipher type on the sub node.
node_groups -> sub_nodes -> backrest -> archive_mode	Specifies if pgBackRest archiving is `on` or `off` on the sub node.

Manually Configuring a Cluster Deploying a Cluster on Remote Nodes