From 0a2719a18bcefdbd815dabe9d5f12f60808a9186 Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan Date: Mon, 27 Jan 2025 17:39:34 +0000 Subject: [PATCH] Filling out content for cli Signed-off-by: Dj Walker-Morgan --- .../pgd/5/cli/command_ref/assess/index.mdx | 135 ++++++++++++ .../pgd/5/cli/command_ref/cluster/show.mdx | 37 +++- .../pgd/5/cli/command_ref/cluster/verify.mdx | 196 ++++++++++++++++++ .../5/cli/command_ref/commit-scope/create.mdx | 0 .../5/cli/command_ref/commit-scope/drop.mdx | 0 .../5/cli/command_ref/commit-scope/index.mdx | 14 ++ .../5/cli/command_ref/commit-scope/show.mdx | 37 ++++ .../5/cli/command_ref/commit-scope/update.mdx | 0 .../5/cli/command_ref/completion/index.mdx | 33 +++ .../pgd/5/cli/command_ref/events/index.mdx | 1 - .../pgd/5/cli/command_ref/events/show.mdx | 16 ++ .../5/cli/command_ref/group/get-option.mdx | 79 +++++++ .../pgd/5/cli/command_ref/group/index.mdx | 14 +- .../5/cli/command_ref/group/set-leader.mdx | 32 +++ .../5/cli/command_ref/group/set-option.mdx | 81 ++++++++ .../docs/pgd/5/cli/command_ref/group/show.mdx | 19 ++ .../groups/{groups.mdx => index.mdx} | 3 +- .../pgd/5/cli/command_ref/groups/list.mdx | 51 +++++ .../docs/pgd/5/cli/command_ref/index.mdx | 3 - .../pgd/5/cli/command_ref/node/get-option.mdx | 89 ++++++++ .../docs/pgd/5/cli/command_ref/node/index.mdx | 8 +- .../pgd/5/cli/command_ref/node/set-option.mdx | 81 ++++++++ .../docs/pgd/5/cli/command_ref/node/show.mdx | 118 +++++++++++ .../cli/command_ref/node/upgrade-postgres.mdx | 42 ++++ .../docs/pgd/5/cli/command_ref/nodes/list.mdx | 70 +++++++ .../docs/pgd/5/cli/command_ref/raft/index.mdx | 11 + .../docs/pgd/5/cli/command_ref/raft/show.mdx | 42 ++++ .../5/cli/command_ref/replication/index.mdx | 12 ++ .../5/cli/command_ref/replication/show.mdx | 41 ++++ product_docs/docs/pgd/5/cli/index.mdx | 26 +-- 30 files changed, 1257 insertions(+), 34 deletions(-) create mode 100644 product_docs/docs/pgd/5/cli/command_ref/commit-scope/create.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/commit-scope/drop.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/commit-scope/index.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/commit-scope/show.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/commit-scope/update.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/group/get-option.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/group/set-leader.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/group/set-option.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/group/show.mdx rename product_docs/docs/pgd/5/cli/command_ref/groups/{groups.mdx => index.mdx} (79%) create mode 100644 product_docs/docs/pgd/5/cli/command_ref/groups/list.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/node/get-option.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/node/set-option.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/node/show.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/node/upgrade-postgres.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/nodes/list.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/raft/index.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/raft/show.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/replication/index.mdx create mode 100644 product_docs/docs/pgd/5/cli/command_ref/replication/show.mdx diff --git a/product_docs/docs/pgd/5/cli/command_ref/assess/index.mdx b/product_docs/docs/pgd/5/cli/command_ref/assess/index.mdx index daba48e5da7..778f4c77734 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/assess/index.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/assess/index.mdx @@ -3,5 +3,140 @@ title: pgd assess navTitle: Assess --- +## Synopsis + The `pgd assess` commands are used to assess the suitability of a Postgres server instance for migration to the EDB Postgres Distributed cluster. +The command must be run with a DSN that connects to the Postgres server instance that you want to assess. The command will check the Postgres server instance for compatibility with the EDB Postgres Distributed cluster, and will provide a report on the compatibility of the Postgres server instance. + +## Options + +The assess command has no command specific options. + +See also [Global Options](../index#global-options). + +## Example + +```bash +pgd assess +__OUTPUT__ +Multiple Databases +------------------ +Multiple databases cannot be part of the same PGD cluster, it's possible to +create a separate PGD cluster for each database, but it's not recommended. +See https://www.enterprisedb.com/docs/pgd/latest/planning/limitations/ for +details. + +Result: Compatible, found only one user database + + +Sequences +--------- +PGD uses distributed sequences, two types are supported, see - +https://www.enterprisedb.com/docs/pgd/latest/sequences/ for details. + +Existing sequences need to be converted to distributed sequences using the +following commands: + + - SELECT bdr.alter_sequence_set_kind('public.quicktest_id_seq', 'galloc') + +Result: Needs conversion to distributed sequences + + +Tables with Multiple Unique Indexes +----------------------------------- +Tables with multiple unique indexes may result in +"multiple_unique_conflicts" conflict, which can be problem when +using PGD as active-active system with concurrent workloads, +see https://www.enterprisedb.com/docs/pgd/latest/conflict- +management/conflicts/02_types_of_conflict/ for details. + +Result: Compatible, no tables with multiple unique indexes found + + +Materialized Views +------------------ +Materialized views are supported by PGD, however DDL commands +on them (CREATE, ALTER, DROP, REFRESH) are not replicated, see +https://www.enterprisedb.com/docs/pgd/latest/ddl/ddl-command-handling/ for +details. + +Result: Compatible, no materialized views found + + +EPAS Queue Tables +----------------- +EPAS Queue Tables are not replicated by PGD, so they only work on per node +basis. + +Result: Compatible, no EPAS Queue Tables found + + +LOCK TABLE Usage +---------------- +LOCK TABLE is not replicated by default by PGD, if you need distributed +LOCK TABLE support, enable "bdr.lock_table_locking" on all nodes, see +https://www.enterprisedb.com/docs/pgd/latest/reference/pgd-settings/ for +details. + +Result: requires static code analysis, could not analyze LOCK TABLE usage +with pg_stat_statements + + +DDL Command Usage +----------------- +There are some limitations in DDL command handling in PGD, see +https://www.enterprisedb.com/docs/pgd/latest/ddl/ddl-command-handling/ for +details. + +Result: Cannot be checked automatically at this time, requires code analysis + + +LISTEN/NOTIFY Usage +------------------- +PGD is compatible with LISTEN/NOTIFY, however it works on each node +separately, just like with standard Postgres + +Result: Could not analyze LISTEN/NOTIFY usage with pg_stat_statements + + +Row-Level Lock Usage +-------------------- +Row-level locks are not replicated by default by PGD, and as such don't work +as concurrency protection across nodes, and conflict resolution will be used +instead, see https://www.enterprisedb.com/docs/pgd/latest/appusage/behavior/ +for details. + +Result: Requires static code analysis, could not analyze row-level locking +commands using pg_stat_statements + + +Advisory Lock Usage +------------------- +Advisory locks are not replicated by PGD, global +advisory lock functionality is provided instead, see +https://www.enterprisedb.com/docs/pgd/latest/reference/functions/#global- +advisory-locks for details. + +Result: Requires static code analysis, could not analyze advisory lock +commands using pg_stat_statements + + +Large Objects +------------- +Large objects are not replicated by PGD, you can +still use "bytea" and other data types normally, see +https://www.enterprisedb.com/docs/pgd/latest/appusage/behavior/ for details. + +Result: Compatible, no large objects found + + +Trigger/Reference Privileges +---------------------------- +PGD enforces stricter access control rules on triggers and reference +columns. See https://www.enterprisedb.com/docs/pgd/latest/security/access- +control/#triggers for details. + +Result: Compatible, no triggers with incompatible privileges found +``` + diff --git a/product_docs/docs/pgd/5/cli/command_ref/cluster/show.mdx b/product_docs/docs/pgd/5/cli/command_ref/cluster/show.mdx index e3bc21b583a..153916926ff 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/cluster/show.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/cluster/show.mdx @@ -23,6 +23,41 @@ The following table lists the options available for the `pgd events show` comman | | --summary | Only show cluster summary information. | | | --health | Only show cluster health information. | -Only one of the above options can be specified at a time. +Only one of the above options can be specified at a time. + +See also [Global Options](../index#global-options). ## Examples + +### Display the cluster information + +```shell +pgd cluster show +__OUTPUT__ +# Summary +Group Name Parent Group Group Type Node Name Node Kind +---------- ------------ --------------- ---------- --------------- +pgd global +dc1 pgd data node-one data +dc1 pgd data node-three data +dc1 pgd data node-two data +sogroup1 pgd subscriber-only sonode-one subscriber-only +sogroup1 pgd subscriber-only sonode2 subscriber-only + +# Health +Check Status Message +----------------- ------ ----------------------------------------------- +Connections Ok All BDR nodes are accessible +Raft Ok Raft Consensus is working correctly +Replication Slots Ok All PGD replication slots are working correctly +Clock Skew Ok Clock drift is within permissible limit +Versions Ok All nodes are running the same PGD version + +# Clock Drift +Reference Node Node Name Clock Drift +-------------- ---------- ----------- +node-one node-two * +node-one node-three * +node-one sonode-one * +node-one sonode2 * +``` diff --git a/product_docs/docs/pgd/5/cli/command_ref/cluster/verify.mdx b/product_docs/docs/pgd/5/cli/command_ref/cluster/verify.mdx index 4ab5b79597b..d2b3e5f91e4 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/cluster/verify.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/cluster/verify.mdx @@ -26,3 +26,199 @@ The following table lists the options available for the `pgd events show` comman With no option set, both setting and arch are verified by default and output is not verbose. ## Examples + +### Verify the cluster settings and architecture + +```shell +pgd cluster verify +__OUTPUT__ +# Architecture + +Cluster has data nodes +---------------------- +Cluster must have at least one data node + +Result: Ok + + +Witness nodes per group +----------------------- +Each data group has at most one witness node + +Result: Ok + + +Witness-only groups +------------------- +Cluster has at most one witness-only group + +Result: Ok + + +Data nodes per group +-------------------- +Each data group has at least one data node + +Result: Ok + + +Empty groups +------------ +There are no empty groups + +Result: Ok + + +# Settings + +max_prepared_transactions +------------------------- +The maximum number of prepared transactions that can be active in parallel. +Needed for CAMO and GROUP COMMIT features to work. + +Result: Ok + + +bdr.raft_group_max_connections +------------------------------ +The maximum number of Raft connections that can be made in a BDR cluster. +Effectively limits how many nodes can exist in the cluster. + +Result: Ok + + +bdr.standby_slot_names +---------------------- +Replication slot names that changes must be replicated to before any other +nodes can receiver changes. + +Result: Ok + + +bdr.writers_per_subscription +---------------------------- +The number of writers that can be attached to a single subscription. This +setting is used to limit the number of parallel writers that can be attached +to a single subscription. + +Result: Ok + + +bdr.standby_slots_min_confirmed +------------------------------- +The minimum number of bdr.standby_slot_names slots that must be confirmed +before a node can receive changes. + +Result: Ok + + +max_connections +--------------- +The maximum number of client connections that can be made to the database. + +Result: Ok + + +wal_level +--------- +The level of information written to the WAL. BDR requires "logical" WAL level. + +Result: Ok + + +bdr.start_workers +----------------- +This setting controls whether PGD workers are started. Without this PGD is not +able to work. Should be only disabled internally by PGD or PGD CLI. + +Result: Ok + + +bdr.xact_replication +-------------------- +Controls whether transactions are replicated. + +Result: Ok + + +bdr.ddl_locking +--------------- +Whether DDL locking is enabled. DDL locking serializes DDL locks across the +cluster and ensures that DML which conflicts with DDL is blocked during the +DDL execution. + +Result: Ok + + +bdr.max_writers_per_subscription +-------------------------------- +The maximum number of writers that can be attached to a single subscription. +This setting sets upper limit for bdr.writers_per_subscription. + +Result: Ok + + +max_replication_slots +--------------------- +The maximum number of replication slots that can exist at the same time. Also +maximum number of origins that can exist at the same time. Must be high enough +for PGD to work. + +Result: Ok + + +max_worker_processes +-------------------- +The maximum number of background processes that can be registered at the same +time. PGD uses several background processes to function. + +Result: Ok + + +track_commit_timestamp +---------------------- +Controls whether the commit timestamp tracking is enabled. BDR requires this +to function. + +Result: Ok + + +bdr.role_replication +-------------------- +Controls whether the role and user related commands are replicated. + +Result: Ok + + +max_wal_senders +--------------- +The maximum number of WAL senders that can ber running at the same time. Must +be high enough for PGD to work. + +Result: Ok + + +shared_preload_libraries +------------------------ +A list of shared libraries that are preloaded into each backend. BDR must be +one of them. + +Result: Ok + + +bdr.replay_progress_frequency +----------------------------- +The frequency at which replay progress is updated. This setting controls how +often the replay progress is updated in the bdr.replication_progress table via +Raft. This table is used to determine how much WAL needs to be kept. + +Result: Ok + + +bdr.accept_connections +---------------------- +Whether the node accepts incoming replication connections from other PGD +nodes. Should only be disabled for internal use by PGD and PGD CLI. + +Result: Ok +``` \ No newline at end of file diff --git a/product_docs/docs/pgd/5/cli/command_ref/commit-scope/create.mdx b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/create.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/product_docs/docs/pgd/5/cli/command_ref/commit-scope/drop.mdx b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/drop.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/product_docs/docs/pgd/5/cli/command_ref/commit-scope/index.mdx b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/index.mdx new file mode 100644 index 00000000000..8d689b8ea2a --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/index.mdx @@ -0,0 +1,14 @@ +--- +title: pgd commit-scope +navTitle: Commit Scope +--- + +The `pgd commit-scope` commands are used to display and manage the commit scopes in the EDB Postgres Distributed cluster. + +## Subcommands + +- [show](show): Show information about a commit scope. +- [create](create): Create a commit scope. +- [update](update): Update a commit scope. +- [drop](drop): Drop a commit scope. + diff --git a/product_docs/docs/pgd/5/cli/command_ref/commit-scope/show.mdx b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/show.mdx new file mode 100644 index 00000000000..b262c036f7e --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/show.mdx @@ -0,0 +1,37 @@ +--- +title: pgd commit-scope show +navTitle: show +--- + +## Synopsis + +The `pgd commit-scope show` command is used to display information about a commit scope in the EDB Postgres Distributed cluster. + +## Syntax + +```shell +pgd commit-scope show [OPTIONS] +``` + +Where `` is the name of the commit scope for which you want to display information. + +## Options + +No command specific options. See [Global Options](../index#global-options). + +## Example + +### Showing a Commit Scope + +The following example shows the information about the commit scope `abc1`: + +```shell +pgd commit-scope abc1 show +__OUTPUT__ +Commit Scope Group Name Rule Definition +------------ ---------- -------------------------------------- +abc1 dc1 ANY 2 (dc1) on replicated group commit +``` + +The `Rule Definition` column shows the rule that defines the commit scope. In this case, the rule is `ANY 2 (dc1) on replicated group commit`. This rule specifies that the commit scope `abc1` requires at least two nodes in the `dc1` group to commit a transaction before it is considered committed. The `dc1` group is a replicated group, so the commit must be replicated to at least two nodes in the group. + diff --git a/product_docs/docs/pgd/5/cli/command_ref/commit-scope/update.mdx b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/update.mdx new file mode 100644 index 00000000000..e69de29bb2d diff --git a/product_docs/docs/pgd/5/cli/command_ref/completion/index.mdx b/product_docs/docs/pgd/5/cli/command_ref/completion/index.mdx index 1b536a7270f..72acf5481e4 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/completion/index.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/completion/index.mdx @@ -3,5 +3,38 @@ title: pgd completion navTitle: Completion --- +## Synopsis + The `pgd completion` commands are used to manage the completion settings for the EDB Postgres Distributed CLI. +## Syntax + +```plaintext +pgd completion +``` + +Where `` is the shell for which to generate the autocompletion script. + +Possible values for shell are `bash`, `fish`, `zsh` and `powershell`. + +## Options + +No command specific options. See [Global Options](../index#global-options). + +## Example + +```shell +pgd completion zsh --dsn '' +``` + +This command would normally be evaluated as part of a shell session's startup files. It generates a completion script for the Zsh shell and writes it to the standard output. Therfore you would add to your `.zshrc` file: + +```shell +eval "$(pgd completion zsh --dsn '')" +``` + + + + + + diff --git a/product_docs/docs/pgd/5/cli/command_ref/events/index.mdx b/product_docs/docs/pgd/5/cli/command_ref/events/index.mdx index 9880dab0192..45a98c30f57 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/events/index.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/events/index.mdx @@ -8,4 +8,3 @@ The `pgd events` commands are used to display the events in the EDB Postgres Dis ## Subcommands - [show](show): Show events. - diff --git a/product_docs/docs/pgd/5/cli/command_ref/events/show.mdx b/product_docs/docs/pgd/5/cli/command_ref/events/show.mdx index 71300d226ec..bd7dad0c392 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/events/show.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/events/show.mdx @@ -23,4 +23,20 @@ The following table lists the options available for the `pgd events show` comman | | --group _groupname_ | Only show events for the group with the specified name. | | -n _number_ | --number _number_ | Show the specified number of events. Defaults to 20. | +See also [Global Options](../index#global-options). + ## Examples + +### Display the last 5 events + +```shell +$ pgd events show -n 5 +__OUTPUT__ +Event Time Event Observer Event Subject Event Source Event Type Event Subtype Event Text Event Detail +------------------------------ -------------- ------------- ------------ ---------- ------------- ------------- ------------------------------------------------------------------------------------------------------- +2025-01-13 08:07:11.383250 UTC node-two node-two consensus ROUTING STATE_CHANGE RAFT_FOLLOWER +2025-01-13 08:07:11.383261 UTC node-two node-one consensus ROUTING STATE_CHANGE WRITE_LEADER dc1 +2025-01-13 08:07:11.383291 UTC node-two node-two consensus ROUTING STATE_CHANGE RAFT_LEADER {"raft_leader":"node-two","group_name":"dc1","read_nodes_version":5,"read_nodes":"node-two,node-three"} +2025-01-13 08:07:14.945816 UTC sonode-one sonode-one consensus RAFT STATE_CHANGE RAFT_FOLLOWER pgd +2025-01-13 08:07:18.904540 UTC sonode2 sonode2 consensus RAFT STATE_CHANGE RAFT_FOLLOWER pgd +``` diff --git a/product_docs/docs/pgd/5/cli/command_ref/group/get-option.mdx b/product_docs/docs/pgd/5/cli/command_ref/group/get-option.mdx new file mode 100644 index 00000000000..514df68fa88 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/group/get-option.mdx @@ -0,0 +1,79 @@ +--- +title: pgd group get-option +navTitle: Get Option +--- + +## Synopsis + +The `pgd group get-option` command is used to get group-level options in the EDB Postgres Distributed cluster. + +## Syntax + +``` +pgd group get-option [OPTIONS]