diff --git a/advocacy_docs/edb-postgres-ai/cloud-service/references/distributed_high_availability/pgd_cli_ba.mdx b/advocacy_docs/edb-postgres-ai/cloud-service/references/distributed_high_availability/pgd_cli_ba.mdx index 78d7e036847..186fd9a4609 100644 --- a/advocacy_docs/edb-postgres-ai/cloud-service/references/distributed_high_availability/pgd_cli_ba.mdx +++ b/advocacy_docs/edb-postgres-ai/cloud-service/references/distributed_high_availability/pgd_cli_ba.mdx @@ -6,7 +6,8 @@ redirects: - /biganimal/latest/using_cluster/pgd_cli_ba/ #generated for BigAnimal URL path removal branch --- -When running a distributed high-availability cluster on Cloud Service, you can use the [PGD CLI](/pgd/latest/cli/) to manage cluster operations. Examples of these operations include switching over write leaders, performing cluster health checks, and viewing various details about nodes, groups, or other aspects of the cluster. +When running a distributed high-availability cluster on Cloud Service, you can use the [PGD CLI](/pgd/latest/cli/) to manage cluster operations. +Examples of these operations include switching over write leaders, performing cluster health checks, and viewing various details about nodes, groups, or other aspects of the cluster. ## Installing the PGD CLI @@ -48,70 +49,93 @@ Without a properly configured `.pgpass`, you receive a database connection error To use the PGD CLI with your database connection string, use the `--dsn` flag with your PGD CLI command: ```bash -pgd show-nodes --dsn "" +pgd nodes list --dsn "" ``` ## PGD commands in Cloud Service -!!!Note - -Three EDB Postgres Distributed CLI commands don't work with distributed high-availability Cloud Service clusters: `create-proxy`, `delete-proxy`, and `alter-proxy-option`. These commands are managed by Cloud Service, as Cloud Service runs on Kubernetes. It's a technical best practice to have the Kubernetes operator handle these functions. -!!! - The examples that follow show the most common PGD CLI commands with a Cloud Service cluster. -### `pgd check-health` +### `pgd cluster show --health` -`pgd check-health` provides statuses with relevant messaging regarding the clock skew of node pairs, node accessibility, the current raft leader, replication slot health, and versioning consistency: +`pgd cluster show --health` provides statuses with relevant messaging regarding the clock skew of node pairs, node accessibility, the current raft leader, replication slot health, and versioning consistency: ``` -$ pgd check-health --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" +pgd cluster show --health --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" __OUTPUT__ -Check Status Message ------ ------ ------- -ClockSkew Ok All BDR node pairs have clockskew within permissible limit -Connection Ok All BDR nodes are accessible -Raft Warning There is no RAFT_LEADER, an election might be in progress -Replslots Ok All BDR replication slots are working correctly -Version Ok All nodes are running same BDR versions +Connections +----------- +Checks if all BDR nodes are accessible. + +Result: Ok, all BDR nodes are accessible + + +Raft +---- +Raft Consensus status. Checks if all data and witness nodes are participating +in raft and have the same leader. + +Result: Ok, raft Consensus is working correctly + + +Replication Slots +----------------- +Checks if all PGD replication slots are working correctly. + +Result: Ok, all PGD replication slots are working correctly + + +Clock Skew +---------- +Clock drift between nodes. Uses raft leader as reference node to calculate +clock drift. High clock drift can affect conflict resolution and potentially +cause inconsistency. + +Result: Ok, clock drift is within permissible limit + + +Versions +-------- +Checks if all nodes are running the same PGD version. + +Result: Ok, all nodes are running the same PGD version ``` -### `pgd show-nodes` +### `pgd nodes list` -`pgd show-nodes` returns all the nodes in the distributed high-availability cluster and their summaries, including name, node id, group, and current/target state: +`pgd nodes list` returns all the nodes in the distributed high-availability cluster and their summaries, including name, node id, group, and current/target state: ``` -$ pgd show-nodes --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" +pgd nodes list--dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" __OUTPUT__ -Node Node ID Group Type Current State Target State Status Seq ID ----- ------- ----- ---- ------------- ------------ ------ ------ -p-mbx2p83u9n-a-1 3537039754 dc1 data ACTIVE ACTIVE Up 1 -p-mbx2p83u9n-a-2 3155790619 p-mbx2p83u9n-a data ACTIVE ACTIVE Up 2 -p-mbx2p83u9n-a-3 2604177211 p-mbx2p83u9n-a data ACTIVE ACTIVE Up 3 +Node Name Group Name Node Kind Join State Node Status +--------- ------------ --------- ---------- ----------- +kaboom dc1_subgroup data ACTIVE Up +kaftan dc1_subgroup data ACTIVE Up +kaolin dc1_subgroup data ACTIVE Up ``` ### `pgd show-groups` -`pgd show-groups` returns all groups in your distributed high-availability Cloud Service cluster. It also notes the node that's the current write leader of each group: +`pgd groups show` returns all groups in your distributed high-availability Cloud Service cluster. ``` -$ pgd show-groups --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" +pgd groups show --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" __OUTPUT__ -Group Group ID Type Parent Group Location Raft Routing Write Leader ------ -------- ---- ------------ -------- ---- ------- ------------ -world 3239291720 global true true p-mbx2p83u9n-a-1 -dc1 4269540889 data p-mbx2p83u9n-a false false -p-mbx2p83u9n-a 2800873689 data world true true p-mbx2p83u9n-a-3 +Group Name Parent Group Name Group Type Nodes +------------ ----------------- ---------- ----- +democluster global 0 +dc1_subgroup democluster data 3 ``` -### `pgd switchover` +### `pgd group set-leader` -`pgd switchover` manually changes the write leader of the group and can be used to simulate a [failover](/pgd/latest/quickstart/further_explore_failover). +`pgd group set-leader` manually changes the write leader of the group and can be used to simulate a [failover](/pgd/latest/quickstart/further_explore_failover). ``` -$ pgd switchover --group-name world --node-name p-mbx2p83u9n-a-2 --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" +pgd group world set-leader kaftan --dsn "postgres://edb_admin@p-mbx2p83u9n-a.pg.biganimal.io:5432/bdrdb?sslmode=require" __OUTPUT__ -switchover is complete +Command executed successfully ``` See the [PGD CLI command reference](/pgd/latest/cli/command_ref/) for the full range of PGD CLI commands and their descriptions. diff --git a/advocacy_docs/edb-postgres-ai/cloud-service/references/supported_cluster_types/distributed_highavailability.mdx b/advocacy_docs/edb-postgres-ai/cloud-service/references/supported_cluster_types/distributed_highavailability.mdx index 2eb8fdf3849..c9610372858 100644 --- a/advocacy_docs/edb-postgres-ai/cloud-service/references/supported_cluster_types/distributed_highavailability.mdx +++ b/advocacy_docs/edb-postgres-ai/cloud-service/references/supported_cluster_types/distributed_highavailability.mdx @@ -19,7 +19,7 @@ The witness node/witness group doesn't host data but exists for management purpo !!!Note - Operations against a distributed high-availability cluster leverage the [EDB Postgres Distributed switchover](/pgd/latest/cli/command_ref/pgd_switchover/) feature, which provides subsecond interruptions during planned lifecycle operations. + Operations against a distributed high-availability cluster leverage the [EDB Postgres Distributed set-leader](/pgd/latest/cli/command_ref/group/set-leader) feature, which provides subsecond interruptions during planned lifecycle operations. ## Single data location diff --git a/product_docs/docs/net_connector/8.0.5.1/12_using_advanced_queueing.mdx b/product_docs/docs/net_connector/8.0.5.1/12_using_advanced_queueing.mdx index 6ca5265864f..58dbb750ade 100644 --- a/product_docs/docs/net_connector/8.0.5.1/12_using_advanced_queueing.mdx +++ b/product_docs/docs/net_connector/8.0.5.1/12_using_advanced_queueing.mdx @@ -76,7 +76,9 @@ To enqueue a message on your .NET application, you must: The following code shows using the `queue.Enqueue` method. !!! Note - This code creates the message and serializes it. This is example code and doesn't compile if copied as it is. You must serialize the message as XML. + +This code creates the message and serializes it. This is example code and doesn't compile if copied as it is. You must serialize the message as XML. +!!! ```csharp using EnterpriseDB.EDBClient; @@ -199,6 +201,7 @@ To dequeue a message on your .NET application, you must: 3. Call the `queue.Dequeue` method. !!! Note + The following code creates the message and serializes it. This is example code and doesn't compile if copied as it is. You must serialize the message as XML. ```csharp @@ -371,7 +374,7 @@ The `EDBAQDequeueMode` class lists all the dequeuer modes available. | Value | Description | | ------------- | ------------------------------------------------------------- | -| Browse | Reads the message without locking. | +| Browse | Reads the message without locking. | | Locked | Reads and gets a write lock on the message. | | Remove | Deletes the message after reading. This is the default value. | | Remove_NoData | Confirms receipt of the message. | @@ -380,58 +383,58 @@ The `EDBAQDequeueMode` class lists all the dequeuer modes available. The `EDBAQDequeueOptions` class lists the options available when dequeuing a message. -| Property | Description | -| -------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| ConsumerName | The name of the consumer for which to dequeue the message. | -| DequeueMode | Set from `EDBAQDequeueMode`. It represents the locking behavior linked with the dequeue option. | -| Navigation | Set from `EDBAQNavigationMode`. It represents the position of the message to fetch. | +| Property | Description | +| -------------- | ----------------------------------------------------------------------------------------------------------------- | +| ConsumerName | The name of the consumer for which to dequeue the message. | +| DequeueMode | Set from `EDBAQDequeueMode`. It represents the locking behavior linked with the dequeue option. | +| Navigation | Set from `EDBAQNavigationMode`. It represents the position of the message to fetch. | | Visibility | Set from `EDBAQVisibility`. It represents whether the new message is dequeued as part of the current transaction. | -| Wait | The wait time for a message as per the search criteria. | -| Msgid | The message identifier. | -| Correlation | The correlation identifier. | -| DeqCondition | The dequeuer condition. It's a Boolean expression. | -| Transformation | The transformation to apply before dequeuing the message. | -| DeliveryMode | The delivery mode of the dequeued message. | +| Wait | The wait time for a message as per the search criteria. | +| Msgid | The message identifier. | +| Correlation | The correlation identifier. | +| DeqCondition | The dequeuer condition. It's a Boolean expression. | +| Transformation | The transformation to apply before dequeuing the message. | +| DeliveryMode | The delivery mode of the dequeued message. | ### EDBAQEnqueueOptions The `EDBAQEnqueueOptions` class lists the options available when enqueuing a message. -| Property | Description | -| ----------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| Property | Description | +| ----------------- | ----------------------------------------------------------------------------------------------------------------- | | Visibility | Set from `EDBAQVisibility`. It represents whether the new message is enqueued as part of the current transaction. | -| RelativeMsgid | The relative message identifier. | -| SequenceDeviation | The sequence when to dequeue the message. | -| Transformation | The transformation to apply before enqueuing the message. | -| DeliveryMode | The delivery mode of the enqueued message. | +| RelativeMsgid | The relative message identifier. | +| SequenceDeviation | The sequence when to dequeue the message. | +| Transformation | The transformation to apply before enqueuing the message. | +| DeliveryMode | The delivery mode of the enqueued message. | ### EDBAQMessage The `EDBAQMessage` class lists a message to enqueue/dequeue. -| Property | Description | -| ------------ | -------------------------------- | -| Payload | The actual message to queue. | -| MessageId | The ID of the queued message. | +| Property | Description | +| --------- | ----------------------------- | +| Payload | The actual message to queue. | +| MessageId | The ID of the queued message. | ### EDBAQMessageProperties The `EDBAQMessageProperties` lists the message properties available. -| Property | Description | -| ---------------- | --------------------------------------------------------------------------------------------- | -| Priority | The priority of the message. | +| Property | Description | +| ---------------- | ---------------------------------------------------------------------------- | +| Priority | The priority of the message. | | Delay | The duration after which the message is available for dequeuing, in seconds. | -| Expiration | The duration for which the message is available for dequeuing, in seconds. | -| Correlation | The correlation identifier. | -| Attempts | The number of attempts taken to dequeue the message. | -| RecipientList | The recipients list that overthrows the default queue subscribers. | -| ExceptionQueue | The name of the queue to move the unprocessed messages to. | -| EnqueueTime | The time when the message was enqueued. | -| State | The state of the message while dequeued. | -| OriginalMsgid | The message identifier in the last queue. | -| TransactionGroup | The transaction group for the dequeued messages. | -| DeliveryMode | The delivery mode of the dequeued message. | +| Expiration | The duration for which the message is available for dequeuing, in seconds. | +| Correlation | The correlation identifier. | +| Attempts | The number of attempts taken to dequeue the message. | +| RecipientList | The recipients list that overthrows the default queue subscribers. | +| ExceptionQueue | The name of the queue to move the unprocessed messages to. | +| EnqueueTime | The time when the message was enqueued. | +| State | The state of the message while dequeued. | +| OriginalMsgid | The message identifier in the last queue. | +| TransactionGroup | The transaction group for the dequeued messages. | +| DeliveryMode | The delivery mode of the dequeued message. | ### EDBAQMessageState @@ -448,11 +451,11 @@ The `EDBAQMessageState` class represents the state of the message during dequeue The `EDBAQMessageType` class represents the types for payload. -| Value | Description | -| --------- | ------------------------------------------------------------------------------------- | -| Raw | The raw message type.

Note: Currently, this payload type isn't supported. | -| UDT | The user-defined type message. | -| XML | The XML type message.

Note: Currently, this payload type isn't supported. | +| Value | Description | +| ----- | ------------------------------------------------------------------------------------ | +| Raw | The raw message type.

Note: Currently, this payload type isn't supported. | +| UDT | The user-defined type message. | +| XML | The XML type message.

Note: Currently, this payload type isn't supported. | ### EDBAQNavigationMode @@ -468,25 +471,26 @@ The `EDBAQNavigationMode` class represents the different types of navigation mod The `EDBAQQueue` class represents a SQL statement to execute `DMBS_AQ` functionality on a PostgreSQL database. -| Property | Description | -| ----------------- | --------------------------------------------------------------------------------------------- | -| Connection | The connection to use. | -| Name | The name of the queue. | +| Property | Description | +| ----------------- | ---------------------------------------------------------------------------------------------- | +| Connection | The connection to use. | +| Name | The name of the queue. | | MessageType | The message type that's enqueued/dequeued from this queue, for example `EDBAQMessageType.Udt`. | -| UdtTypeName | The user-defined type name of the message type. | -| EnqueueOptions | The enqueue options to use. | -| DequeuOptions | The dequeue options to use. | -| MessageProperties | The message properties to use. | +| UdtTypeName | The user-defined type name of the message type. | +| EnqueueOptions | The enqueue options to use. | +| DequeuOptions | The dequeue options to use. | +| MessageProperties | The message properties to use. | ### EDBAQVisibility The `EDBAQVisibility` class represents the visibility options available. -| Value | Description | -| --------- | ----------------------------------------------------------- | +| Value | Description | +| --------- | ---------------------------------------------------------- | | Immediate | The enqueue/dequeue isn't part of the ongoing transaction. | -| On_Commit | The enqueue/dequeue is part of the current transaction. | +| On_Commit | The enqueue/dequeue is part of the current transaction. | !!! Note - - To review the default options for these parameters, see [DBMS_AQ](../../epas/latest/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/). + + - To review the default options for these parameters, see [DBMS_AQ](/epas/latest/reference/oracle_compatibility_reference/epas_compat_bip_guide/03_built-in_packages/02_dbms_aq/). - EDB advanced queueing functionality uses user-defined types for calling enqueue/dequeue operations. `Server Compatibility Mode=NoTypeLoading` can't be used with advanced queueing because `NoTypeLoading` doesn't load any user-defined types. diff --git a/product_docs/docs/pgd/5/cdc-failover.mdx b/product_docs/docs/pgd/5/cdc-failover.mdx new file mode 100644 index 00000000000..53013c95577 --- /dev/null +++ b/product_docs/docs/pgd/5/cdc-failover.mdx @@ -0,0 +1,105 @@ +--- +title: CDC Failover support +navTitle: CDC Failover support +description: CDC Failover support (PGD Logical Slot Failover) with EDB Postgres Advanced Server and EDB Postgres Extended Server (PGD 5.7 and later only). +deepToC: true +--- + +!!!warning Availability +This is a PGD 5.7 and later feature. It is not supported on earlier versions of PGD. +!!! + +## Background + +Earlier versions of PGD have allowed the creation of logical replication slots on nodes that can provide a feed of the logical changes happening to the data within the database. These logical replication slots have been local to the node and not replicated. Apart from only replicating changes on the particular node, this has presented challenges when faced with node failover within the cluster. In that scenario, a consumer of the logical replication off a node which fails has no replica of the slot on another node to continue consuming from. + +While solutions to this can be engineered using a subscriber-only node as an intermediary, it does significantly raise the cost of logical replication. + +## CDC Failover support + +To address this need, PGD 5.7 introduces CDC Failover support. This is an optionally enabled feature which activates automatic logical slot replication across the cluster. This, in turn, allows a consumer of a logical slot’s replication to receive change data from any node when a failure occurs. + +### How CDC Failover works + +When a logical slot is created on a node with CDC Failover support enabled, the slot is replicated across the cluster. This means that the slot is available for consumption on any node in the cluster. When a node fails, the slot can be consumed from another node in the cluster. This allows for the continuation of the logical replication stream without interruption. + +If, though, the consumer of the slot connects to a different node in the cluster, the previous connection the consumer had will be closed by PGD. This is to ensure that the slot is not being consumed from multiple nodes at the same time. In the background, PGD is using its Raft consensus protocol to ensure that the slot is only being consumed from one node at a time; this does mean that the guarantee of only one slot being consumed at a time does not hold in split-brain scenarios. + +Currently CDC Failover support is a global option that is controlled by a top-group option. The `failover_slot_scope` top-group option can currently be set to (and defaults to) local which disables replication of logical slots or `global` which enables the replication of all non-temporary logical slots created in the PGD database. + +Temporary logical slots will not be replicated as they have a lifetime scoped to the session that created them and will go away when that session ends. + +### At-least-once delivery guarantees + +CDC Failover support takes steps to ensure that the consumer receives all changes at least once. This is done by holding back slots until delivery has been confirmed, at which point the slot is then advanced on all nodes in an asynchronous manner. In the case of a failure on the node where the slot was being consumed, the slot would be held until the consumer connected to a node in the cluster. This would then allow the slot to progress. + +!!! Important +If a consuming application disconnects and doesn’t reconnect the slot will remain on held back on every node in the cluster. As this consumes disk and memory, it is essential that this situation is avoided; applications which consume slots must return to consuming as soon as possible. +!!! + +### Exactly-once delivery + +Currently, there is no way to ensure exactly-once delivery, and we expect consuming applications to manage the discarding of previously completed transactions. + +## Enabling CDC Failover support + +To enable CDC Failover support run the SQL command and call the [`bdr.alter_node_group_option`](/pgd/5/reference/nodes-management-interfaces#bdralter_node_group_option) function with the following parameters: + +```sql +select bdr.alter_node_group_option(, + 'failover_slot_scope', + 'global'); + +``` + +Replacing `` with the name of your cluster’s top level group. + +If you do not know the name, it is the group with a node_group_parent_id equal to 0 in `[`bdr.node_group`](/pgd/5/reference/catalogs-visible#bdrnode_group)`. You can also use: + +```sql +SELECT bdr.alter_node_group_option( + node_group_name, + 'failover_slot_scope', + 'global') + from bdr.node_group + where node_group_parent_id=0; +``` + +To ensure you are setting the correct, top-level group’s option. + +Once enabled you can use: + +```sql +SELECT pg_create_logical_replication_slot('myslot', + 'test_decoding'); +``` + +To create a new globally replicated slot. + +Note that logical replication slots created before the option is set to `global` will not be replicated. Only new slots will be replicated. + +Failover slots can also be created with the `CREATE_REPLICATION_SLOT` command on a replication connection. + +The status of failover slots is tracked in the [`bdr.failover_replication_slots`](/pgd/5/reference/catalogs-visible#bdrfailover_replication_slots) table. + +## CDC Failover support with Postgres 17+ + +For Postgres 17 and later, support for failover was added to allow standbys to be resumed, through an option in `pg_create_logical_replication_slot` named `failover`. This new setting requires that, no matter what the setting of `failover_slot_scope`, you must also set `failover` to `true`. + +```sql +SELECT pg_create_logical_replication_slot('myslot', + 'test_decoding', + failover=>true); +``` + +## Limitations + +The CDC Failover Slot support comes with certain limitations. + +* CDC Failover slot support requires the latest versions of PGD (5.7+) and the latest minor releases of Postgres-Extended or EPAS (available Feb 2025\). +* CDC Failover support is a global option and cannot be set on a per-slot basis. It is possible though, because changing the enabled status of CDC Failover does not affect previously provisioned slots, to enable it (set to `global`), create a replicated slot, then disable it (set to `local`), to create a singular replicated slot. +* CDC Failover support is not supported on temporary slots. +* CDC Failover support is not supported on slots created with the `failover` option set to `false`. +* CDC Failover support works with EDB Postgres Advanced Server and EDB Postgres Extended Server only. It is not supported on community Postgres installations. +* Existing slots are not automatically converted into failover slots when the option is enabled. +* While Postgres’s built-in functions such as `pg_logical_slot_get_changes()` can be used they won’t ensure that the slot is not being decoded anywhere else and can’t update replication progress accurately across the cluster. Therefore it’s recommended not to rely on the function to receive decoded changes. 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 new file mode 100644 index 00000000000..46ede7a1e2d --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/assess/index.mdx @@ -0,0 +1,142 @@ +--- +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](/pgd/latest/cli/command_ref/#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/index.mdx b/product_docs/docs/pgd/5/cli/command_ref/cluster/index.mdx new file mode 100644 index 00000000000..86798da5766 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/cluster/index.mdx @@ -0,0 +1,12 @@ +--- +title: pgd cluster +navTitle: Cluster +--- + +The `pgd cluster` commands are used to manage the EDB Postgres Distributed cluster. + +## Subcommands + +- [show](show): Show cluster-level information. +- [verify](verify): Verify cluster-level information. + 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 new file mode 100644 index 00000000000..a9d24fbdd23 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/cluster/show.mdx @@ -0,0 +1,63 @@ +--- +title: pgd cluster show +navTitle: Show +--- + +## Synopsis + +The `pgd cluster show` command is used to display the cluster-level information in the EDB Postgres Distributed cluster. + +## Syntax + +```plaintext +pgd cluster show [OPTIONS] +``` + +## Options + +The following table lists the options available for the `pgd events show` command: + +| Short | Long | Description | +|-------------|---------------------|---------------------------------------------------------| +| | --clock-drift | Only show detailed clock drift information. | +| | --summary | Only show cluster summary information. | +| | --health | Only show cluster health information. | + +Only one of the above options can be specified at a time. + +See also [Global Options](/pgd/latest/cli/command_ref/#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 new file mode 100644 index 00000000000..050e04a832e --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/cluster/verify.mdx @@ -0,0 +1,224 @@ +--- +title: pgd cluster verify +navTitle: Verify +--- + +## Synopsis + +The `pgd cluster verify` command is used to verify the configuration of an EDB Postgres Distributed cluster. + +## Syntax + +```plaintext +pgd cluster show [OPTIONS] +``` + +## Options + +The following table lists the options available for the `pgd events show` command: + +| Short | Long | Description | +|-------|------------|------------------------------------------| +| | --settings | Verify Postgres settings in the cluster. | +| | --arch | Verify the cluster architecture | +| -v | --verbose | Display verbose output. | + +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..fb1311c5587 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/create.mdx @@ -0,0 +1,43 @@ +--- +title: pgd commit-scope create +navTitle: create +--- + +## Synopsis + +The `pgd commit-scope create` command is used to create a commit scope in the EDB Postgres Distributed cluster. + +## Syntax + +```shell +pgd commit-scope create [OPTIONS] [GROUP_NAME] +``` + +Where `` is the name of the commit scope to create. + +The `` is the rule that defines the commit scope. The rule specifies the conditions that must be met for a transaction to be considered committed. See [Commit Scopes](/pgd/latest/commit-scopes) and [Commit Scope Rules](/pgd/latest/commit-scopes/commit-scope-rules/) for more information on the rule syntax. + +The optional `[GROUP_NAME]` is the name of the group to which the commit scope belongs. If omitted, it defaults to the top-level group. + +## Options + +No command specific options. See [Global Options](/pgd/latest/cli/command_ref/#global-options). + +## Examples + +### Creating a Commit Scope + +The following example creates a commit scope named `abc1` with the rule `ANY 2 (dc1) on replicated group commit`: + +```shell +pgd commit-scope create abc1 "ANY 2 (dc1) on replicated group commit" +__OUTPUT__ +Status Message +------ ----------------------------- +OK Command executed successfully +``` + + + + + 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..dd6798d7305 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/drop.mdx @@ -0,0 +1,35 @@ +--- +title: pgd commit-scope drop +navTitle: drop +--- + +## Synopsis + +The `pgd commit-scope drop` command is used to drop a commit scope from the EDB Postgres Distributed cluster. + +## Syntax + +```shell +pgd commit-scope drop [OPTIONS] [GROUP_NAME] +``` + +Where `` is the name of the commit scope to drop. +The optional `[GROUP_NAME]` is the name of the group to which the commit scope belongs. If omitted, it defaults to the top-level group. + +## Options + +No command specific options. See [Global Options](/pgd/latest/cli/command_ref/#global-options). + +## Examples + +### Drop a Commit Scope + +The following example drops the commit scope named `abc1`: + +```shell +pgd commit-scope abc1 drop +__OUTPUT__ +Status Message +------ ----------------------------- +OK Command executed successfully +``` 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..0a17174d7f1 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/show.mdx @@ -0,0 +1,36 @@ +--- +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](/pgd/latest/cli/command_ref/#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..06c296d424c --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/commit-scope/update.mdx @@ -0,0 +1,38 @@ +--- +title: pgd commit-scope update +navTitle: update +--- + +## Synopsis + +The `pgd commit-scope update` command is used to update a commit scope in the EDB Postgres Distributed cluster. + +## Syntax + +```shell +pgd commit-scope update [OPTIONS] [GROUP_NAME] +``` + +Where `` is the name of the commit scope to update. + +The `` is the rule that defines the commit scope. The rule specifies the conditions that must be met for a transaction to be considered committed. See [Commit Scopes](/pgd/latest/commit-scopes) and [Commit Scope Rules](/pgd/latest/commit-scopes/commit-scope-rules/) for more information on the rule syntax. + +The optional `[GROUP_NAME]` is the name of the group to which the commit scope belongs. If omitted, it defaults to the top-level group. + +## Options + +No command specific options. See [Global Options](/pgd/latest/cli/command_ref/#global-options). + +## Examples + +### Updating a Commit Scope + +The following example updates the commit scope `abc1` with the rule `ANY 3 (dc1) on replicated group commit`: + +```shell +pgd commit-scope abc1 update "ANY 1 (dc1) on replicated group commit" +__OUTPUT__ +Status Message +------ ----------------------------- +OK Command executed successfully +``` 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 new file mode 100644 index 00000000000..5e7227627a6 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/completion/index.mdx @@ -0,0 +1,40 @@ +--- +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](/pgd/latest/cli/command_ref/#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 new file mode 100644 index 00000000000..45a98c30f57 --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/events/index.mdx @@ -0,0 +1,10 @@ +--- +title: pgd events +navTitle: Events +--- + +The `pgd events` commands are used to display the events in the EDB Postgres Distributed cluster. + +## 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 new file mode 100644 index 00000000000..ae66d7385ce --- /dev/null +++ b/product_docs/docs/pgd/5/cli/command_ref/events/show.mdx @@ -0,0 +1,42 @@ +--- +title: pgd events show +navTitle: show +--- + +## Synopsis + +The `pgd events show` command is used to display the events in the EDB Postgres Distributed cluster. With no additional flags, the command displays the 20 most recent events for all nodes and groups. + +## Syntax + +```plaintext +pgd events show [OPTIONS] +``` + +## Options + +The following table lists the options available for the `pgd events show` command: + +| Short | Long | Description | +|-------------|---------------------|---------------------------------------------------------| +| | --node _nodename_ | Only show events for the node with the specified name. | +| | --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](/pgd/latest/cli/command_ref/#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..1d56d6fe937 --- /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]