Command reference
=================

The command name for the PGD command line interface is ``pgd`` .

Synopsis
--------

The EDB Postgres Distributed Command Line Interface (PGD CLI) is a tool
to manage your EDB Postgres Distributed cluster. It allows you to run
commands against EDB Postgres Distributed clusters. You can use it to
inspect and manage cluster resources.

Commands
--------

- :ref:`Cluster configuration <Cluster configuration>`  : Cluster-level commands for managing the cluster.

- :ref:`pgd cluster show <pgd cluster show>`  : Show cluster-level information.

- :ref:`pgd cluster verify <pgd cluster verify>`  : Verify cluster-level information.

- :ref:`Viewing groups and replication sets <Viewing groups and replication sets>`  : Group-level commands for managing groups.

- :ref:`pgd cluster show <pgd cluster show>`  : Show group-level information.

- :ref:`pgd group set-option <pgd group set-option>`  : Set group-level options.

- :ref:`pgd group get-option <pgd group get-option>`  : Get group-level options.

- :ref:`pgd group set-leader <pgd group set-leader>`  : Set the write leader of a group (perform a
  switchover).

- :ref:`Viewing groups and replication sets <Viewing groups and replication sets>`  : Group related commands for listing groups. -
  :ref:`pgd commit-scopes list <pgd commit-scopes list>`  : List groups.

- :ref:`Nodes with differences <Nodes with differences>`  : Node-level commands for managing nodes.

- :ref:`Running pgd node setup <Running pgd node setup>`  : Setup a node in the cluster.

- :ref:`pgd cluster show <pgd cluster show>`  : Show node-level information.

- :ref:`pgd node part <pgd node part>`  : Part a PGD node from an active cluster.

- :ref:`pgd group set-option <pgd group set-option>`  : Set node-level options.

- :ref:`pgd group get-option <pgd group get-option>`  : Get node-level options.

- :ref:`pgd node set-config <pgd node set-config>`  : Set node-level configuration.

- :ref:`pgd node get-config <pgd node get-config>`  : Get node-level configuration.

- :ref:`pgd node upgrade <pgd node upgrade>`  : Perform a major version upgrade of a PGD Postgres
  node.

- :ref:`pgd node start <pgd node start>`  : Start the Postgres instance on a node.

- :ref:`pgd node stop <pgd node stop>`  : Stop the Postgres instance on a node.

- :ref:`pgd node restart <pgd node restart>`  : Restart the Postgres instance on a node.

- :ref:`Node management <Node management>`  : Node related commands for listing nodes. -
  :ref:`pgd commit-scopes list <pgd commit-scopes list>`  : List nodes.

- :ref:`Monitoring degrade events <Monitoring degrade events>`  : Event log commands for viewing events. -
  :ref:`pgd cluster show <pgd cluster show>`  : Show events.

- :ref:`DML and DDL replication and nonreplication <DML and DDL replication and nonreplication>`  : Replication related-commands for managing
  replication. - :ref:`pgd cluster show <pgd cluster show>`  : Show replication information.

- :ref:`Part a node (Raft protocol version 6003 and above) <Part a node (Raft protocol version 6003 and above)>`  : Raft related commands for managing Raft consensus.

- :ref:`pgd cluster show <pgd cluster show>`  : Show information about Raft state.

- :ref:`pgd raft enable <pgd raft enable>`  : Enable the Raft consensus worker on one or more
  nodes.

- :ref:`pgd raft disable <pgd raft disable>`  : Disable the Raft consensus worker on one or more
  nodes.

- :ref:`pgd group set-leader <pgd group set-leader>`  : Transfer Raft leadership to a specified node.

- :ref:`pgd raft restore <pgd raft restore>`  : Restore Raft consensus by removing the minimum set of
  nodes needed.

- :ref:`pgd raft sync-snapshot <pgd raft sync-snapshot>`  : Synchronize Raft state across all nodes.

- :ref:`pgd commit-scope create <pgd commit-scope create>`  : Commit scope related commands for managing PGD commit
  scopes.

- :ref:`pgd cluster show <pgd cluster show>`  : Show information about a commit-scope.

- :ref:`pgd commit-scope create <pgd commit-scope create>`  : Create a commit-scope.

- :ref:`pgd commit-scope update <pgd commit-scope update>`  : Update a commit-scope.

- :ref:`pgd commit-scope drop <pgd commit-scope drop>`  : Drop a commit-scope.

- :ref:`pgd commit-scopes list <pgd commit-scopes list>`  : List commit scopes.

- :ref:`Using pgd assess <Using pgd assess>`  : Assesses a Postgres server’s PGD compatibility.

- :ref:`pgd completion <pgd completion>`  : Generate shell completion scripts.

User roles
----------

Each ``pgd`` command connects as a specific Postgres role, or, for a few
node-management commands, requires only OS-level access. Every command
page includes a section stating the role it needs.

These roles are created automatically when the BDR extension is
installed, so you don’t need to create them yourself, only grant them to
the user connecting with the CLI. See :ref:`PGD predefined roles <PGD predefined roles>`  for the full
privilege list behind each one.

.. csv-table::
  :header: Role,Description
  :widths: 10,30
  :align: left
  :class: longtable

  `bdr_superuser`,"Full PGD management. Granted `ALL` privileges directly on every table and function in the `bdr` schema, plus `pg_read_all_stats`. This is a superset of what every other role grants, even though it isn't formal role inheritance."
  `bdr_monitor`,"Read-only cluster monitoring. Inherits `bdr_read_all_stats` and `pg_read_all_stats` (not `pg_read_all_settings`). Many `show`/`list` commands still require `bdr_superuser`, since they use internal functions that aren't granted to `bdr_monitor`."
  `bdr_read_all_stats`,Reads PGD statistics and catalog views. Inherits `pg_read_all_stats`.
  `bdr_application`,"Application-level access, such as reading commit scopes. A separate role, not part of the monitoring chain."
  Postgres superuser,"Required for `ALTER SYSTEM`, `CREATE EXTENSION`, and `pg_upgrade`. Separate from `bdr_superuser`."
  OS user (`pg_ctl`),"Required by `pgd node start`/`stop`/`restart`, which are OS-level operations. No database role is checked."

Global Options
--------------

All commands accept the following global options:

.. csv-table::
  :header: Short,Long,Description
  :widths: 12,10,25
  :align: left
  :class: longtable

  `-f`,`--config-file`,"Name/Path to config file.<br/>This is ignored if --dsn flag is present<br/>Default ""/etc/edb/pgd-cli/pgd-cli-config.yml"""
  "",`--dsn`,"Database connection string<br/>For example ""host=bdr-a1 port=5432 dbname=pgddb user=postgres""<br/>Also set by `PGD_CLI_DSN` environment variable."
  `-h`,`--help`,Help for pgd - will show specific help for any command used
  `-o`,`--output`,"Output format: `json`, `psql`, `modern`, `markdown`, `simple` (see  :ref:`Output formats<Output formats>` )"

Additional Options
------------------

Run ``pgd -V`` to see the version information for the pgd CLI.

Output formats
--------------

Used with the ``-o`` /``--output`` option:

.. csv-table::
  :header: Format,Description
  :widths: 10,30
  :align: left
  :class: longtable

  simple,Simple format - Output as a simple ASCII table (Default).
  json,"JSON format - Output as a JSON document, non-tabular"
  psql,PSQL format - Output as an ASCII table in the style of PSQL
  modern,Modern format - Output as a table using box characters
  markdown,Markdown table format - Output as a markdown compatible ASCII table

.. toctree::
  :maxdepth: 3

  REFERENCE--reference--cli--command_ref--assess
  REFERENCE--reference--cli--command_ref--cluster--index
  REFERENCE--reference--cli--command_ref--commit-scope--index
  REFERENCE--reference--cli--command_ref--completion
  REFERENCE--reference--cli--command_ref--events--index
  REFERENCE--reference--cli--command_ref--group--index
  REFERENCE--reference--cli--command_ref--groups--index
  REFERENCE--reference--cli--command_ref--node--index
  REFERENCE--reference--cli--command_ref--nodes--index
  REFERENCE--reference--cli--command_ref--raft--index
  REFERENCE--reference--cli--command_ref--replication--index