diff --git a/product_docs/docs/pgd/3.7/harp/01_release_notes/harp2.4.1_rel_notes.mdx b/product_docs/docs/pgd/3.7/harp/01_release_notes/harp2.4.1_rel_notes.mdx deleted file mode 100644 index 3e093ba9644..00000000000 --- a/product_docs/docs/pgd/3.7/harp/01_release_notes/harp2.4.1_rel_notes.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Version 2.4.1" ---- - -Released: 16 May 2024 - -This is a patch release of HARP 2 that includes internal maintenance fixes. - -| Type | Description | -| ---- |------------ | -| Change | Routine security library upgrades | - diff --git a/product_docs/docs/pgd/3.7/harp/01_release_notes/index.mdx b/product_docs/docs/pgd/3.7/harp/01_release_notes/index.mdx index 6f2ae940ddf..8467591676c 100644 --- a/product_docs/docs/pgd/3.7/harp/01_release_notes/index.mdx +++ b/product_docs/docs/pgd/3.7/harp/01_release_notes/index.mdx @@ -1,7 +1,6 @@ --- title: Release Notes navigation: -- harp2.4.1_rel_notes - harp2.4.0_rel_notes - harp2.3.2_rel_notes - harp2.3.1_rel_notes @@ -28,7 +27,6 @@ The release notes in this section provide information on what was new in each re | Version | Release Date | | ----------------------- | ------------ | -| [2.4.1](harp2.4.1_rel_notes) | 15 May 2024 | | [2.4.0](harp2.4.0_rel_notes) | 05 Mar 2024 | | [2.3.2](harp2.3.2_rel_notes) | 17 Oct 2023 | | [2.3.1](harp2.3.1_rel_notes) | 27 Jul 2023 | diff --git a/product_docs/docs/pgd/4/rel_notes/index.mdx b/product_docs/docs/pgd/4/rel_notes/index.mdx index 1139ec2af5d..64abe56586a 100644 --- a/product_docs/docs/pgd/4/rel_notes/index.mdx +++ b/product_docs/docs/pgd/4/rel_notes/index.mdx @@ -2,7 +2,6 @@ title: "EDB Postgres Distributed Release notes" navTitle: "Release notes" navigation: -- pgd_4.3.5_rel_notes - pgd_4.3.4_rel_notes - pgd_4.3.3_rel_notes - pgd_4.3.2+p1_rel_notes @@ -30,7 +29,6 @@ The EDB Postgres Distributed documentation describes the latest version of EDB P | Release Date | EDB Postgres Distributed | BDR | HARP | CLI | TPAexec | |--------------|-------------------------------------|-------|-------|-------|--------------------------------------------------------------| -| 16 May 2024 | [4.3.5](pgd_4.3.5_rel_notes) | 4.3.4 | 2.4.1 | 1.1.2 | [23.32](/tpa/latest/rel_notes/tpa_23.32_rel_notes/) | | 05 Mar 2024 | [4.3.4](pgd_4.3.4_rel_notes) | 4.3.4 | 2.4 | 1.1.2 | [23.29](/tpa/latest/rel_notes/tpa_23.29_rel_notes/) | | 14 Nov 2023 | [4.3.3](pgd_4.3.3_rel_notes) | 4.3.3 | 2.3.2 | 1.1.2 | [23.24](/tpa/latest/rel_notes/tpa_23.24_rel_notes) | | 17 Oct 2023 | [4.3.2+p1](pgd_4.3.2+p1_rel_notes) | 4.3.2 | 2.3.2 | 1.1.1 | [23.20](/tpa/latest/rel_notes/tpa_23.20_rel_notes) | diff --git a/product_docs/docs/pgd/4/rel_notes/pgd_4.3.5_rel_notes.mdx b/product_docs/docs/pgd/4/rel_notes/pgd_4.3.5_rel_notes.mdx deleted file mode 100644 index f2f8883e710..00000000000 --- a/product_docs/docs/pgd/4/rel_notes/pgd_4.3.5_rel_notes.mdx +++ /dev/null @@ -1,29 +0,0 @@ ---- -title: "Release notes for EDB Postgres Distributed version 4.3.5" -navTitle: "Version 4.3.5" -redirects: - - /pgd/latest/bdr/release_notes/bdr4.3.5_rel_notes/ ---- - -Released: 16 May 2024 - -EDB Postgres Distributed version 4.3.5 is a patch release of EDB Postgres Distributed 4, which includes bug fixes for issues identified in previous versions. - -!!! Note -This version is required for EDB Postgres Advanced Server versions 12.15, 13.11, 14.10, 15.5, and later. -!!! - -| Component | Version | Type | Description | Addresses | -|-----------|---------|-------------|----------------------------------------------------------------------------------------------------------------|----------------| -| HARP | 2.4.1 | Change | Routine security library upgrades. | | -| BDR | 4.3.5 | Enhancement | BDR now logs the completion of an extension upgrade. | | -| BDR | 4.3.5 | Enhancement | Each autopartition task is now executed in its own transaction. | | -| BDR | 4.3.5 | Enhancement | DETACH CONCURRENTLY is now used to drop partitions. | RT101407/35476 | -| BDR | 4.3.5 | Enhancement | `bdr_superuser` is now granted use of `pg_file_settings` and `pg_show_all_file_settings()`. | | -| BDR | 4.3.5 | Enhancement | `bdr_init_physical` now stops the initial replication connection and starts it only when needed. | RT102828/35305 | -| BDR | 4.3.5 | Bug Fix | Improved handling of node group configuration parameter `check_constraints`. | RT99956/31896 | -| BDR | 4.3.5 | Bug Fix | Fixed an issue to prevent potential segfault in `bdr.monitor_group_versions()`. | RT102290/34051 | -| BDR | 4.3.5 | Bug Fix | BDR now uses `bdr.default_sequence_kind` when updating sequence kind of existing sequences upon node creation. | | -| BDR | 4.3.5 | Bug Fix | Manage rights elevation for trusted extensions | | - - diff --git a/product_docs/docs/pgd/5/cli/command_ref/index.mdx b/product_docs/docs/pgd/5/cli/command_ref/index.mdx index bf6dec3966b..1ef87e61391 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/index.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/index.mdx @@ -1,10 +1,10 @@ --- title: Command reference -navTitle: Command reference -description: A reference guide to the commands available in the PGD CLI. +redirects: + - /pgd/latest/cli/command_ref/pgd_show-camo/ --- -The command name for the PGD command line interface is `pgd`. +pgd is the command name for the PGD command line interface. ## Synopsis diff --git a/product_docs/docs/pgd/5/cli/command_ref/pgd_create-proxy.mdx b/product_docs/docs/pgd/5/cli/command_ref/pgd_create-proxy.mdx index 5dff042d0ce..9a05b8f82df 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/pgd_create-proxy.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/pgd_create-proxy.mdx @@ -10,10 +10,6 @@ Creates proxy in the EDB Postgres Distributed cluster and attaches it to the given group. The proxy name must be unique across the cluster and match with the name given in the corresponding proxy config file. -Use the proxy mode to route connections to Write Leader (default), Read Nodes -(read-only), or both (any). Proxy listens on 'listen_port' for Write Leader -connections while on 'read_listen_port' for Read Nodes connections. - ```sh pgd create-proxy [flags] @@ -23,14 +19,9 @@ pgd create-proxy [flags] ```text - Example 1 (attach new proxy called proxy-a1 to group group_a, with 'default' mode) - - $ pgd create-proxy --proxy-name proxy-a1 --group-name group_a - proxy created successfully - - Example 2 (attach new proxy called proxy-b1 to group group_b, with 'any' mode) + Example 1 (attach new proxy called proxy-a1 to group bdrgroup) - $ pgd create-proxy --proxy-name proxy-b1 --group-name group_b --proxy-mode any + $ pgd create-proxy --proxy-name proxy-a1 --group-name bdrgroup proxy created successfully ``` @@ -40,17 +31,13 @@ pgd create-proxy [flags] ```text --group-name string group name -h, --help help for create-proxy - --proxy-mode string proxy mode (default, read-only, any); proxy will route connections to - - default - Write Leader - read-only - Read Nodes - any - both Write Leader and Read Nodes (default "default") --proxy-name string proxy name ``` ### Options inherited from parent commands ```text - -f, --config-file string config file; ignored if + -f, --config-file string config file; ignored if --dsn flag is present (default "/etc/edb/pgd-cli/pgd-cli-config.yml") --dsn string database connection string e.g."host=bdr-a1 port=5432 dbname=bdrdb user=postgres " diff --git a/product_docs/docs/pgd/5/cli/command_ref/pgd_set-group-options.mdx b/product_docs/docs/pgd/5/cli/command_ref/pgd_set-group-options.mdx index 0e52a6e9077..5f5444bf3e0 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/pgd_set-group-options.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/pgd_set-group-options.mdx @@ -12,7 +12,6 @@ You can set the following group options with this command: - 'enable_proxy_routing' - 'location' - 'route_writer_max_lag' -- 'route_reader_max_lag' Both 'enable_raft' and 'enable_proxy_routing' must be true if proxy is attached to the group. @@ -58,7 +57,7 @@ pgd set-group-options [flags] ### Options inherited from parent commands ```text - -f, --config-file string config file; ignored if + -f, --config-file string config file; ignored if --dsn flag is present (default "/etc/edb/pgd-cli/pgd-cli-config.yml") --dsn string database connection string e.g."host=bdr-a1 port=5432 dbname=bdrdb user=postgres " diff --git a/product_docs/docs/pgd/5/cli/command_ref/pgd_set-node-options.mdx b/product_docs/docs/pgd/5/cli/command_ref/pgd_set-node-options.mdx index 8db3d6d7245..d7c03d390d1 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/pgd_set-node-options.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/pgd_set-node-options.mdx @@ -12,7 +12,6 @@ You can set the following node options with this command: - 'route_fence' - 'route_priority' - 'route_writes' -- 'route_reads' Use 'pgd show-nodes -o json' to view option values for each node. @@ -55,7 +54,7 @@ pgd set-node-options [flags] ### Options inherited from parent commands ```text - -f, --config-file string config file; ignored if + -f, --config-file string config file; ignored if --dsn flag is present (default "/etc/edb/pgd-cli/pgd-cli-config.yml") --dsn string database connection string e.g."host=bdr-a1 port=5432 dbname=bdrdb user=postgres " diff --git a/product_docs/docs/pgd/5/cli/command_ref/pgd_set-proxy-options.mdx b/product_docs/docs/pgd/5/cli/command_ref/pgd_set-proxy-options.mdx index f5f5b083ee8..d3d4038dece 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/pgd_set-proxy-options.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/pgd_set-proxy-options.mdx @@ -15,20 +15,9 @@ You can set the following proxy options with this command: - 'server_conn_keepalive' - 'server_conn_timeout' - 'consensus_grace_period' -- 'read_listen_address' -- 'read_listen_port' -- 'read_max_client_conn' -- 'read_max_server_conn' -- 'read_server_conn_keepalive' -- 'read_server_conn_timeout' -- 'read_consensus_grace_period' After updating any of these options, restart proxy. -Set 'listen_port' to non-zero value to route traffic to the Write Leader and -set 'read_listen_port' to non-zero value to route traffic to Read nodes. -Setting it to zero will disable the respective routing. - Use 'pgd show-proxies -o json' to view option values for each proxy. @@ -48,13 +37,13 @@ pgd set-proxy-options [flags] Example 2 (multiple --option flags are allowed) - $ pgd set-proxy-options --proxy-name proxy-a1 --option listen_address=0.0.0.0 --option listen_port=0 + $ pgd set-proxy-options --proxy-name proxy-a1 --option listen_address=0.0.0.0 --option listen_port=6432 proxy options updated successfully, please restart proxy service Example 3 (use double quote if option value has spaces or special characters) - $ pgd set-proxy-options --proxy-name proxy-a1 --option "listen_address = 0.0.0.0" --option "consensus_grace_period=1h 30m 5s" + $ pgd set-proxy-options --proxy-name proxy-a1 --option "listen_address = 0.0.0.0" --option "listen_port = 6432" proxy options updated successfully, please restart proxy service ``` diff --git a/product_docs/docs/pgd/5/cli/command_ref/pgd_show-groups.mdx b/product_docs/docs/pgd/5/cli/command_ref/pgd_show-groups.mdx index 63f2a97f9f6..a36359a89a5 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/pgd_show-groups.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/pgd_show-groups.mdx @@ -30,11 +30,11 @@ pgd show-groups [flags] $ pgd show-groups - Group Group ID Type Parent Group Location Raft Routing Raft Leader Write Leader - ----- -------- ---- ------------ -------- ---- ------- ----------- ------------ - bdrgroup 1360502012 global world true false bdr-a2 - group_a 3618712053 data bdrgroup a true true bdr-a2 bdr-a1 - group_b 402614658 data bdrgroup b true true bdr-b1 bdr-b1 + Group Group ID Type Parent Group Location Raft Routing Write Leader + ----- -------- ---- ------------ -------- ---- ------- ------------ + bdrgroup 1360502012 global true false + group_a 3618712053 data bdrgroup a true true bdr-a1 + group_b 402614658 data bdrgroup b true true bdr-b1 group_c 2808307099 data bdrgroup c false false group_so 2123208041 subscriber-only bdrgroup c false false @@ -49,7 +49,7 @@ pgd show-groups [flags] ### Options inherited from parent commands ```text - -f, --config-file string config file; ignored if + -f, --config-file string config file; ignored if --dsn flag is present (default "/etc/edb/pgd-cli/pgd-cli-config.yml") --dsn string database connection string e.g."host=bdr-a1 port=5432 dbname=bdrdb user=postgres " diff --git a/product_docs/docs/pgd/5/cli/command_ref/pgd_show-nodes.mdx b/product_docs/docs/pgd/5/cli/command_ref/pgd_show-nodes.mdx index bad1ff00df8..7281c5d271a 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/pgd_show-nodes.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/pgd_show-nodes.mdx @@ -95,7 +95,7 @@ pgd show-nodes [flags] ### Options inherited from parent commands ```text - -f, --config-file string config file; ignored if + -f, --config-file string config file; ignored if --dsn flag is present (default "/etc/edb/pgd-cli/pgd-cli-config.yml") --dsn string database connection string e.g."host=bdr-a1 port=5432 dbname=bdrdb user=postgres " diff --git a/product_docs/docs/pgd/5/cli/command_ref/pgd_show-proxies.mdx b/product_docs/docs/pgd/5/cli/command_ref/pgd_show-proxies.mdx index f916395e9e1..685cc1b7d10 100644 --- a/product_docs/docs/pgd/5/cli/command_ref/pgd_show-proxies.mdx +++ b/product_docs/docs/pgd/5/cli/command_ref/pgd_show-proxies.mdx @@ -24,12 +24,12 @@ pgd show-proxies [flags] $ pgd show-proxies - Proxy Group Listen Addrs Listen Port Read Listen Addrs Read Listen Port - ----- ----- ------------ ----------- ----------------- ---------------- - proxy-a1 group_a [0.0.0.0] 6432 [0.0.0.0] 6433 - proxy-a2 group_a [0.0.0.0] 6432 [0.0.0.0] 6433 - proxy-b1 group_b [0.0.0.0] 6432 [0.0.0.0] 6433 - proxy-b2 group_b [0.0.0.0] 6432 [0.0.0.0] 6433 + Proxy Group Listen Addresses Listen Port + ----- ----- ---------------- ----------- + proxy-a1 group_a [0.0.0.0] 6432 + proxy-a2 group_a [0.0.0.0] 6432 + proxy-b1 group_b [0.0.0.0] 6432 + proxy-b2 group_b [0.0.0.0] 6432 ``` @@ -42,7 +42,7 @@ pgd show-proxies [flags] ### Options inherited from parent commands ```text - -f, --config-file string config file; ignored if + -f, --config-file string config file; ignored if --dsn flag is present (default "/etc/edb/pgd-cli/pgd-cli-config.yml") --dsn string database connection string e.g."host=bdr-a1 port=5432 dbname=bdrdb user=postgres " diff --git a/product_docs/docs/pgd/5/cli/configuring_cli.mdx b/product_docs/docs/pgd/5/cli/configuring_cli.mdx index 895ec4560e0..37422d707d4 100644 --- a/product_docs/docs/pgd/5/cli/configuring_cli.mdx +++ b/product_docs/docs/pgd/5/cli/configuring_cli.mdx @@ -1,7 +1,6 @@ --- title: "Configuring PGD CLI" navTitle: "Configuring PGD CLI" -description: "Configuring PGD CLI for simpler connections to your PGD cluster" --- PGD CLI can be installed on any system that can connect to the PGD cluster. To use PGD CLI, you need a user with PGD superuser privileges or equivalent. The PGD user with superuser privileges is the [bdr_superuser role](../security). An example of an equivalent user is edb_admin on a BigAnimal distributed high-availability cluster. diff --git a/product_docs/docs/pgd/5/cli/discover_connections.mdx b/product_docs/docs/pgd/5/cli/discover_connections.mdx index d1147559b2f..04e2a3689d8 100644 --- a/product_docs/docs/pgd/5/cli/discover_connections.mdx +++ b/product_docs/docs/pgd/5/cli/discover_connections.mdx @@ -3,7 +3,6 @@ title: "Discovering connection strings" navTitle: "Discovering connection strings" indexdepth: 2 deepToC: true -description: "How to obtain the correct connection strings for your PGD-powered deployment." --- You can install PGD CLI on any system that can connect to the PGD cluster. To use PGD CLI, you need a user with PGD superuser privileges or equivalent. The PGD user with superuser privileges is the [bdr_superuser role](../security). An example of an equivalent user is edb_admin on an EDB BigAnimal distributed high-availability cluster. diff --git a/product_docs/docs/pgd/5/cli/index.mdx b/product_docs/docs/pgd/5/cli/index.mdx index f95b828e8b7..34e8c3a061a 100644 --- a/product_docs/docs/pgd/5/cli/index.mdx +++ b/product_docs/docs/pgd/5/cli/index.mdx @@ -1,9 +1,9 @@ --- -title: "EDB Postgres Distributed Command Line Interface (PGD CLI)" +title: "EDB Postgres Distributed Command Line Interface" navTitle: "PGD CLI" -indexCards: simple +indexCards: none navigation: -- installing +- installing_cli - using_cli - configuring_cli - discover_connections @@ -13,23 +13,9 @@ directoryDefaults: description: "The PGD Command Line Interface (CLI) is a tool to manage your EDB Postgres Distributed cluster" --- -The EDB Postgres Distributed Command Line Interface (PGD CLI) is a tool for managing your EDB Postgres Distributed cluster. It's the key tool for inspecting and managing cluster resources. +The EDB Postgres Distributed Command Line Interface (PGD CLI) is a tool for managing your EDB Postgres Distributed cluster. It allows you to run commands against EDB Postgres Distributed clusters. It's installed automatically on systems in a TPA-deployed PGD cluster. Or it can be installed manually on systems that can connect to any PGD cluster, such as EDB BigAnimal distributed high-availability clusters or PGD clusters deployed using the EDB PGD for Kubernetes operator. -It allows you to run commands against EDB Postgres Distributed clusters to: - * Determine the health of the cluster, inspect the cluster's configuration, and manage the cluster's resources. - * Inspect and manage the cluster's nodes, groups, and proxies. - * Perform switchover operations on the write leaders of groups. - -PGD CLI is installed automatically on systems in a TPA-deployed PGD cluster. - -You can also install it manually on Linux and macOS systems that can connect to a PGD cluster, including: - * EDB BigAnimal distributed high-availability clusters. - * PGD clusters deployed using the EDB PGD for Kubernetes operator. - * Manually deployed PGD clusters. - * TPA-deployed PGD clusters. - - - + diff --git a/product_docs/docs/pgd/5/cli/installing/index.mdx b/product_docs/docs/pgd/5/cli/installing/index.mdx deleted file mode 100644 index af78ef30dde..00000000000 --- a/product_docs/docs/pgd/5/cli/installing/index.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: "Installing PGD CLI" -navTitle: "Installing PGD CLI" -redirects: - - /pgd/latest/cli/installing_cli -deepToC: true -indexCards: simple -description: Installing the PGD CLI on various systems. ---- - -You can install PGD CLI on any system that can connect to the PGD cluster. Linux and macOS are currently supported platforms to install PGD CLI on. - diff --git a/product_docs/docs/pgd/5/cli/installing/macos.mdx b/product_docs/docs/pgd/5/cli/installing/macos.mdx deleted file mode 100644 index 0c291c72a12..00000000000 --- a/product_docs/docs/pgd/5/cli/installing/macos.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: Installing PGD CLI on macOS -navTitle: macOS -description: Installing PGD CLI on macOS ---- - -PGD CLI is available for macOS as a [Homebrew](https://brew.sh/) formula. To install it, run the following commands: - -```shell -brew tap enterprisedb/tap -brew install pgd-cli -``` - -To verify the installation, run: - -```shell -pgd --version -``` - - -[Next: Using PGD CLI](../using_cli) diff --git a/product_docs/docs/pgd/5/cli/installing/tpa.mdx b/product_docs/docs/pgd/5/cli/installing/tpa.mdx deleted file mode 100644 index eaf43b0ee7f..00000000000 --- a/product_docs/docs/pgd/5/cli/installing/tpa.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Installing PGD CLI with TPA" -navTitle: "TPA" -description: "Installing PGD CLI with Trusted Postgres Architect" ---- - -By default, Trusted Postgres Architect installs and configures PGD CLI on each PGD node. - -If you want to install PGD CLI on any non-PGD instance in the cluster, attach the pgdcli role to that instance in Trusted Postgres Architect's configuration file before deploying. - -See [Trusted Postgres Architect](/tpa/latest/) for more information. - -[Next: Using PGD CLI](../using_cli) diff --git a/product_docs/docs/pgd/5/cli/installing/linux.mdx b/product_docs/docs/pgd/5/cli/installing_cli.mdx similarity index 57% rename from product_docs/docs/pgd/5/cli/installing/linux.mdx rename to product_docs/docs/pgd/5/cli/installing_cli.mdx index 83b75a91d59..1695307879a 100644 --- a/product_docs/docs/pgd/5/cli/installing/linux.mdx +++ b/product_docs/docs/pgd/5/cli/installing_cli.mdx @@ -1,16 +1,24 @@ --- -title: Installing PGD CLI on Linux -navTitle: Linux -description: Installing PGD CLI on Linux +title: "Installing PGD CLI" +navTitle: "Installing PGD CLI" +deepToC: true --- - PGD CLI is available for most Linux distributions. You can install it from the EDB repositories, which you can access with your EDB account. PGD users and BigAnimal users, including those on a free trial, have an EDB account and access to PGD CLI. +You can install PGD CLI on any system that can connect to the PGD cluster. To use PGD CLI, you need a user with PGD superuser privileges or equivalent. The PGD user with superuser privileges is the [bdr_superuser role](../security). An example of an equivalent user is edb_admin on an EDB BigAnimal distributed high-availability cluster. -## Obtain your EDB subscription token +## Installing automatically with Trusted Postgres Architect (TPA) + +By default, Trusted Postgres Architect installs and configures PGD CLI on each PGD node. If you want to install PGD CLI on any non-PGD instance in the cluster, attach the pgdcli role to that instance in Trusted Postgres Architect's configuration file before deploying. See [Trusted Postgres Architect](/tpa/latest/) for more information. + +## Installing manually on Linux + +PGD CLI is installable from the EDB repositories, which you can access with your EDB account. PGD users and BigAnimal users, including those on a free trial, have an EDB account and access to PGD CLI. + +### Obtain your EDB subscription token These repositories require a token to enable downloads from them. To obtain your token, log in to [EDB Repos 2.0](https://www.enterprisedb.com/repos-downloads). If this is your first time visiting the EDB Repos 2.0 page, you must select **Request Access** to generate your token. Once a generated token is available, select the **Copy** icon to copy it to your clipboard, or select the eye icon to view it. -## Set the EDB_SUBSCRIPTION_TOKEN environment variable +### Set the EDB_SUBSCRIPTION_TOKEN environment variable Once you have the token, execute the command shown for your operating system, substituting your token for ``. @@ -20,7 +28,7 @@ export EDB_SUBSCRIPTION_TOKEN= Then run the appropriate commands for your operating system. -## Install on Debian or Ubuntu +### Install on Debian or Ubuntu ```bash curl -1sSLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed/setup.deb.sh" | sudo -E bash @@ -41,7 +49,7 @@ You can now install the PGD CLI package using the command: sudo apt-get install edb-pgd5-cli ``` -## Install on RHEL, Rocky, AlmaLinux, or Oracle Linux +### Install on RHEL, Rocky, AlmaLinux, or Oracle Linux ```bash curl -1sSLf "https://downloads.enterprisedb.com/$EDB_SUBSCRIPTION_TOKEN/postgres_distributed/setup.rpm.sh" | sudo -E bash @@ -62,7 +70,4 @@ You can now install the PGD CLI package using the command: sudo yum install edb-pgd5-cli ``` -[Next: Using PGD CLI](../using_cli) - - - +[Next: Using PGD CLI](using_cli) diff --git a/product_docs/docs/pgd/5/cli/using_cli.mdx b/product_docs/docs/pgd/5/cli/using_cli.mdx index 511d98767fc..fa1c89e3c71 100644 --- a/product_docs/docs/pgd/5/cli/using_cli.mdx +++ b/product_docs/docs/pgd/5/cli/using_cli.mdx @@ -1,7 +1,6 @@ --- title: "Using PGD CLI" navTitle: "Using PGD CLI" -description: "How to use the PGD Command Line Interface (CLI) to manage your EDB Postgres Distributed cluster." --- ## What is the PGD CLI? diff --git a/product_docs/docs/pgd/5/index.mdx b/product_docs/docs/pgd/5/index.mdx index 58b2f7e25b8..53109360781 100644 --- a/product_docs/docs/pgd/5/index.mdx +++ b/product_docs/docs/pgd/5/index.mdx @@ -13,32 +13,34 @@ navigation: - "#Get Started" - quickstart - planning + - architectures + - choosing_server + - deployments + - other_considerations + - limitations - deploy-config - "#Using" - appusage - - ddl - - sequences - - "#Administration" - node_management - postgres-configuration - - routing - - backup + - ddl - security - - monitoring - - testingandtuning - - upgrades - - "#Tools" - - cli - - "#PGD Features" + - sequences - durability - consistency - parallelapply - repsets + - routing + - backup + - monitoring + - cli + - transaction-streaming + - testingandtuning - striggers - scaling - twophase - - transaction-streaming - tssnapshots + - upgrades - "#Reference" - reference --- @@ -66,4 +68,3 @@ Postgres 16 support is only available in EDB Postgres Distributed 5.3 and later !!! For feature compatibility with compatible servers, see [Choosing a Postgres distribution](/pgd/latest/planning/choosing_server). - diff --git a/product_docs/docs/pgd/5/known_issues.mdx b/product_docs/docs/pgd/5/known_issues.mdx index c9c75df33b8..69e112e20c6 100644 --- a/product_docs/docs/pgd/5/known_issues.mdx +++ b/product_docs/docs/pgd/5/known_issues.mdx @@ -67,12 +67,4 @@ release. settings to ensure only active nodes in the cluster are listed for connection. -- When using - [`bdr.add_commit_scope`](/pgd/latest/reference/functions#bdradd_commit_scope) - if a new commit scope is added which has the same name as a commit scope on - any group, then the commit scope silently overwrites the commit scope but - retains the original group the scope was associated with (if any). To modify - a commit scope safely, use - [`bdr.alter_commit_scope`](/pgd/latest/reference/functions#bdralter_commit_scope). - -Details of other design or implementation [limitations](planning/limitations) are also available. +Details of other design or implementation [limitations](limitations) are also available. diff --git a/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx b/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx index 24623799579..247f411daba 100644 --- a/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx +++ b/product_docs/docs/pgd/5/quickstart/quick_start_docker.mdx @@ -108,6 +108,33 @@ You'll use TPA to provision and deploy PGD. If you previously installed TPA, you [TPA supports several distributions of Linux](/tpa/latest/INSTALL/) as a host platform. These examples are written for Ubuntu 22.04, but steps are similar for other supported platforms. +!!! Important + If the Linux host platform you're using is running [cgroups](https://en.wikipedia.org/wiki/Cgroups) v2, you need to disable it and enable cgroups v1 while using TPA to deploy to Docker. + + To check for cgroup v2, run: + + ```shell + mount | grep cgroup | head -1 + ``` + + If you do **not** see a line beginning: + + `tmpfs on /sys/fs/cgroup type tmpfs` + + Then you need to to disable cgroup v2. To do this, run: + + ```shell + echo 'GRUB_CMDLINE_LINUX=systemd.unified_cgroup_hierarchy=false' | sudo tee /etc/default/grub.d/cgroup.cfg + ``` + + Then update the grub bootloader and reboot by running: + + ```shell + sudo update-grub + sudo reboot + ``` + + ### Install the TPA package ```shell @@ -149,8 +176,7 @@ tpaexec configure democluster \ --location-names dc1 \ --pgd-proxy-routing local \ --no-git \ - --hostnames-unsorted \ - --keyring-backend legacy + --hostnames-unsorted ``` You specify the PGD-Always-ON architecture (`--architecture PGD-Always-ON`), which @@ -174,11 +200,9 @@ You set the notional location of the nodes to `dc1` using `--location-names`. Yo By default, TPA commits configuration changes to a Git repository. For this example, you don't need to do that, so pass the `--no-git` flag. -You also ask TPA to generate repeatable hostnames for the nodes by passing `--hostnames-unsorted`. Otherwise, it selects hostnames at random from a predefined list of suitable words. +Finally, you ask TPA to generate repeatable hostnames for the nodes by passing `--hostnames-unsorted`. Otherwise, it selects hostnames at random from a predefined list of suitable words. -Finally, `--keyring-backend legacy` tells TPA to select the legacy version of the keyring backend. Secrets are stored with an older keyring backend, as the version of Ubuntu this example is based on doesn't support the newer keyring backend. - -This command creates a subdirectory called `democluster` in the current working directory. It contains the `config.yml` configuration file TPA uses to create the cluster. You can view it using: +This command creates a subdirectory in the current working directory called `democluster`. It contains the `config.yml` configuration file TPA uses to create the cluster. You can view it using: ```shell less democluster/config.yml @@ -194,11 +218,22 @@ less democluster/config.yml - [`tpaexec configure`](/tpa/latest/tpaexec-configure/) in the Trusted Postgres Architect documentation - [Docker platform](/tpa/latest/platform-docker/) in the Trusted Postgres Architect documentation +### Provisioning the cluster + +Next, allocate the resources needed to run the configuration you just created using the [`tpaexec provision`](/tpa/latest/tpaexec-provision/) command: + +```shell +tpaexec provision democluster +``` + +Since you specified Docker as the platform, TPA creates a Docker image, containers, networks, and so on. + +!!! SeeAlso "Further reading" + - [`tpaexec provision`](/tpa/latest/tpaexec-provision/) in the Trusted Postgres Architect documentation ### Deploying the cluster -You can now [deploy](/tpa/latest/tpaexec-deploy/) the distributed cluster. -For Docker deployments, this will both provision the required Docker containers and deploy the software to those containers: +With configuration in place and infrastructure provisioned, you can now [deploy](/tpa/latest/tpaexec-deploy/) the distributed cluster: ```shell tpaexec deploy democluster diff --git a/product_docs/docs/pgd/5/reference/catalogs-internal.mdx b/product_docs/docs/pgd/5/reference/catalogs-internal.mdx index ece72baa72b..699a20199cd 100644 --- a/product_docs/docs/pgd/5/reference/catalogs-internal.mdx +++ b/product_docs/docs/pgd/5/reference/catalogs-internal.mdx @@ -25,10 +25,10 @@ Internal catalog table that tracks cluster membership events for a given PGD node. Specifically, it tracks: * Node joins (to the cluster) -* Raft state changes (that is, whenever the node changes its role in the consensus -protocol - leader, follower, or candidate to leader) - see [Monitoring Raft consensus](../monitoring/sql#monitoring-raft-consensus) +* Raft state changes (i.e. whenever the node changes its role in the consensus +protocol - leader, follower or candidate to leader) - see [Monitoring Raft Consensus](../monitoring/sql#monitoring-raft-consensus) * Whenever a worker has errored out (see [bdr.workers](/pgd/latest/reference/catalogs-visible/#bdrworkers) -and [Monitoring PGD replication workers](../monitoring/sql#monitoring-pgd-replication-workers)) +and [Monitoring PGD Replication Workers](../monitoring/sql#monitoring-pgd-replication-workers)) #### `bdr.event_history` columns @@ -44,8 +44,8 @@ and [Monitoring PGD replication workers](../monitoring/sql#monitoring-pgd-replic ### `bdr.event_summary` -A view of the `bdr.event_history` catalog that displays the information in a more -human-friendly format. Specifically, it displays the event types and subtypes +A view of the `bdr.event_history` catalog that display the information in a more +human-friendly format. Specifically, it displays the event types and sub-types as textual representations, rather than integers. ### `bdr.node_config` @@ -56,7 +56,7 @@ An internal catalog table with per node configuration options. | Name | Type | Description | | ----------------------- | -------- | ---------------------------------------- | -| node_id | oid | The node ID | +| node_id | oid | The node id | | node_route_priority | int | Priority assigned to this node | | node_route_fence | boolean | Switch to fence this node | | node_route_writes | boolean | Switch to allow writes | @@ -71,27 +71,14 @@ An internal catalog table with per node group configuration options. | Name | Type | Description | | ----------------------- | -------- | ---------------------------------------- | -| node_group_id | oid | The node group ID | +| node_group_id | oid | The node group id | | route_writer_max_lag | bigint | Maximum write lag accepted | | route_reader_max_lag | bigint | Maximum read lag accepted | | route_writer_wait_flush | boolean | Switch if we need to wait for the flush | ### `bdr.node_group_routing_config_summary` -Per-node-group routing configuration options. - -#### `bdr.node_group_routing_config_summary` columns - -| Name | Type | Description | -|-------------------------|---------|-----------------------------------------------------------------| -| node_group_name | name | Node group name | -| location | name | Node group location | -| enable_proxy_routing | boolean | Group proxy routing enabled? | -| node_group_type | text | Node group type (one of "global", "data", or "subscriber-only") | -| route_writer_max_lag | bigint | Maximum write lag accepted | -| route_reader_max_lag | bigint | Maximum read lag accepted | -| route_writer_wait_flush | boolean | Wait for flush | - +Per node group routing configuration options. ### `bdr.node_group_routing_info` @@ -99,39 +86,20 @@ An internal catalog table holding current routing information for a proxy. #### `bdr.node_group_routing_info` columns -| Name | Type | Description | -|--------------------|-------|-----------------------------| -| node_group_id | oid | The node group ID | -| write_node_id | oid | Current write node | -| prev_write_node_id | oid | Previous write node | -| read_node_ids | oid[] | List of read-only nodes IDs | +| Name | Type | Description | +| -------------------- | -------- | -------------------------------------- | +| node_group_id | oid | The node group id tha this proxy uses | +| write_node_id | oid | Current write node | +| prev_write_node_id | oid | Previous write node | +| read_node_ids | oid[] | List of read nodes IDs | ### `bdr.node_group_routing_summary` -A view of `bdr.node_group_routing_info` catalog that shows the information in more friendly way. - -#### `bdr.node_group_routing_summary` columns -| Name | Type | Description | -|---------------------|--------|-----------------------------| -| node_group_name | name | The node group name | -| write_lead | name | The current write lead | -| previous_write_lead | name | The previous write lead | -| read_nodes | name[] | The current read-only nodes | +A view of `bdr.node_group_routing_info` catalog which shows the information in more friendly way ### `bdr.node_routing_config_summary` -A friendly view of the per node routing configuration options. -Shows the node name rather than the oid and shorter field names. - -#### `bdr.node_routing_config_summary` columns -| Name | Type | Description | -|----------------|---------|--------------------------------| -| node_name | name | The node name | -| route_priority | int | Priority assigned to this node | -| route_fence | boolean | Switch to fence this node | -| route_writes | boolean | Switch to allow writes | -| route_reads | boolean | Switch to allow reads | -| route_dsn | text | The interface of this node | +Per node routing configuration options. ### `bdr.proxy_config` @@ -139,53 +107,24 @@ An internal catalog table holding proxy specific configurations. #### `bdr.proxy_config` columns -| Name | Type | Description | -|-----------------------------|----------|------------------------------------------------------------------------------| -| proxy_name | name | The name of the proxy | -| node_group_id | oid | The node group ID that this proxy uses | -| listen_port | int | Port that the proxy uses for read-write connections (set to 0 disables port) | -| max_client_conn | int | Number of maximum read-write client connections that the proxy accepts | -| max_server_conn | int | Number of maximum read-write connections that the server accepts | -| server_conn_timeout | interval | Timeout for the read-write server connections | -| server_conn_keepalive | interval | Interval between the server connection keep alive | -| fallback_group_timeout | interval | Timeout needed for the fallback | -| fallback_group_ids | oid[] | List of group IDs to be used for the fallback | -| listen_addrs | text[] | Listen address | -| read_listen_port | int | Port that the proxy uses for read-only connections (set to 0 disables port) | -| read_max_client_conn | int | Number of maximum read-only client connections that the proxy accepts | -| read_max_server_conn | int | Number of maximum read-only connections that the server accepts | -| read_server_conn_timeout | interval | Timeout for the server read-only connections | -| read_server_conn_keepalive | interval | Interval between the server read-only connection keep alive | -| read_listen_addrs | text[] | Listen address for read-only connections | -| read_consensus_grace_period | interval | Duration for which proxy continues to route even upon loss of consensus | +| Name | Type | Description | +| ---------------------- | -------- | ------------------------------------------------------------------------ | +| proxy_name | name | The name of the proxy | +| node_group_id | oid | The node group id that this proxy uses | +| listen_port | int | Port that the proxy uses | +| max_client_conn | int | Number of maximum client connections that the proxy accepts | +| max_server_conn | int | Number of maximum connections that the server accepts | +| server_conn_timeout | interval | Timeout for the server connections | +| server_conn_keepalive | interval | Interval between the server connection keep alive | +| fallback_group_timeout | interval | Timeout needed for the fallback | +| fallback_group_ids | oid[] | List of group IDs to be used for the fallback | +| listen_addrs | text[] | Listen address | ### `bdr.proxy_config_summary` -A friendly view of per proxy instance specific configuration options. - -#### `bdr.proxy_config_summary` columns -| Name | Type | Description | -|---------------------------------|----------|-------------------------------------------------------------------------------| -| proxy_name | name | The name of the proxy | -| node_group_name | name | The node group name that this proxy uses | -| listen_port | int | Port that the proxy uses for read-write connections (set to -1 disables port) | -| max_client_conn | int | Number of maximum read-write client connections that the proxy accepts | -| max_server_conn | int | Number of maximum read-write connections that the server accepts | -| server_conn_timeout | interval | Timeout for the read-write server connections | -| server_conn_keepalive | interval | Interval between the server connection keep alive | -| node_group_enable_proxy_routing | boolean | Does the group the proxy is in enable proxy routing | -| node_group_location | name | The group's location value | -| fallback_group_timeout | interval | Timeout needed for the fallback | -| fallback_group_ids | oid[] | List of group IDs to be used for the fallback | -| listen_addrs | text[] | Listen address | -| read_listen_port | int | Port that the proxy uses for read-only connections (set to -1 disables port) | -| read_max_client_conn | int | Number of maximum read-only client connections that the proxy accepts | -| read_max_server_conn | int | Number of maximum read-only connections that the server accepts | -| read_server_conn_timeout | interval | Timeout for the server read-only connections | -| read_server_conn_keepalive | interval | Interval between the server read-only connection keep alive | -| read_listen_addrs | text[] | Listen address for read-only connections | -| read_consensus_grace_period | interval | Duration for which proxy continues to route even upon loss of consensus | +Per proxy instance specific configuration options. + ### `bdr.sequence_kind` diff --git a/product_docs/docs/pgd/5/reference/functions.mdx b/product_docs/docs/pgd/5/reference/functions.mdx index c0e7bbd7e74..456ebe3d4d6 100644 --- a/product_docs/docs/pgd/5/reference/functions.mdx +++ b/product_docs/docs/pgd/5/reference/functions.mdx @@ -1141,14 +1141,6 @@ bdr.alter_commit_scope( rule TEXT) ``` -#### Note - -When using `bdr.add_commit_scope` if a new commit scope is added which has the -same name as a commit scope on any group, then the commit scope silently -overwrites the commit scope but retains the original group the scope was -associated with (if any). To modify a commit scope safely, use -[`bdr.alter_commit_scope`](#bdralter_commit_scope). - ### `bdr.remove_commit_scope` Drops a single rule in a commit scope. If you define multiple rules for the commit scope, you must invoke this function once per rule to fully remove the entire commit scope. diff --git a/product_docs/docs/pgd/5/reference/index.json b/product_docs/docs/pgd/5/reference/index.json index fdaa8f28993..cfbe6393bb9 100644 --- a/product_docs/docs/pgd/5/reference/index.json +++ b/product_docs/docs/pgd/5/reference/index.json @@ -172,6 +172,7 @@ "list-of-node-states": "/pgd/latest/reference/nodes#list-of-node-states", "node-management-commands": "/pgd/latest/reference/nodes#node-management-commands", "bdr_init_physical": "/pgd/latest/reference/nodes#bdr_init_physical", + "bdralter_node_group_config": "/pgd/latest/reference/nodes-management-interfaces#bdralter_node_group_config", "bdralter_node_group_option": "/pgd/latest/reference/nodes-management-interfaces#bdralter_node_group_option", "bdralter_node_interface": "/pgd/latest/reference/nodes-management-interfaces#bdralter_node_interface", "bdralter_node_option": "/pgd/latest/reference/nodes-management-interfaces#bdralter_node_option", @@ -184,7 +185,6 @@ "bdrpromote_node": "/pgd/latest/reference/nodes-management-interfaces#bdrpromote_node", "bdrswitch_node_group": "/pgd/latest/reference/nodes-management-interfaces#bdrswitch_node_group", "bdrwait_for_join_completion": "/pgd/latest/reference/nodes-management-interfaces#bdrwait_for_join_completion", - "bdralter_node_group_config": "/pgd/latest/reference/nodes-management-interfaces#bdralter_node_group_config", "bdrcreate_proxy": "/pgd/latest/reference/routing#bdrcreate_proxy", "bdralter_proxy_option": "/pgd/latest/reference/routing#bdralter_proxy_option", "bdrdrop_proxy": "/pgd/latest/reference/routing#bdrdrop_proxy", diff --git a/product_docs/docs/pgd/5/reference/index.mdx b/product_docs/docs/pgd/5/reference/index.mdx index ed0d54fd9fe..219ca41f3c6 100644 --- a/product_docs/docs/pgd/5/reference/index.mdx +++ b/product_docs/docs/pgd/5/reference/index.mdx @@ -242,6 +242,7 @@ The reference section is a definitive listing of all functions, views, and comma ## [Node management interfaces](nodes-management-interfaces) + * [`bdr.alter_node_group_config`](nodes-management-interfaces#bdralter_node_group_config) * [`bdr.alter_node_group_option`](nodes-management-interfaces#bdralter_node_group_option) * [`bdr.alter_node_interface`](nodes-management-interfaces#bdralter_node_interface) * [`bdr.alter_node_option`](nodes-management-interfaces#bdralter_node_option) @@ -254,7 +255,6 @@ The reference section is a definitive listing of all functions, views, and comma * [`bdr.promote_node`](nodes-management-interfaces#bdrpromote_node) * [`bdr.switch_node_group`](nodes-management-interfaces#bdrswitch_node_group) * [`bdr.wait_for_join_completion`](nodes-management-interfaces#bdrwait_for_join_completion) - * [`bdr.alter_node_group_config`](nodes-management-interfaces#bdralter_node_group_config) ## [Routing functions](routing) diff --git a/product_docs/docs/pgd/5/reference/nodes-management-interfaces.mdx b/product_docs/docs/pgd/5/reference/nodes-management-interfaces.mdx index 992776f83f6..613634dcd9f 100644 --- a/product_docs/docs/pgd/5/reference/nodes-management-interfaces.mdx +++ b/product_docs/docs/pgd/5/reference/nodes-management-interfaces.mdx @@ -6,11 +6,96 @@ indexdepth: 2 You can add and remove nodes dynamically using the SQL interfaces. +## `bdr.alter_node_group_config` + +This function changes the configuration parameters of an existing PGD group. +Options with NULL value (default for all of them) aren't modified. + +!!! Warning + This function only exists for compatibility with PGD4 and 3.7. + Please use [`bdr.alter_node_group_option`](#bdralter_node_group_option) instead. + +### Synopsis + +```sql +bdr.alter_node_group_config(node_group_name text, + insert_to_update boolean DEFAULT NULL, + update_to_insert boolean DEFAULT NULL, + ignore_redundant_updates boolean DEFAULT NULL, + check_full_tuple boolean DEFAULT NULL, + apply_delay interval DEFAULT NULL, + check_constraints boolean DEFAULT NULL, + num_writers int DEFAULT NULL, + enable_wal_decoder boolean DEFAULT NULL, + streaming_mode text DEFAULT NULL, + default_commit_scope text DEFAULT NULL) +``` + +### Parameters + +- `node_group_name` — Name of an existing PGD group. The local node must be part + of the group. +- `insert_to_update` — Reserved for backward compatibility. +- `update_to_insert` — Reserved for backward compatibility. + This option is deprecated and will be disabled or removed in future + versions of PGD. Use `bdr.alter_node_set_conflict_resolver` instead. +- `ignore_redundant_updates` — Reserved for backward compatibility. +- `check_full_tuple` — Reserved for backward compatibility. +- `apply_delay` — Reserved for backward compatibility. +- `check_constraints` — Whether the apply process checks the constraints + when writing replicated data. +- `num_writers` — Number of parallel writers for subscription backing + this node group. -1 means the default (as specified by the + GUC `bdr.writers_per_subscription`) is used. Valid values + are either -1 or a positive integer. +- `enable_wal_decoder` — Enables/disables the decoding worker process. + You can't enable the decoding worker process if `streaming_mode` is + already enabled. +- `streaming_mode` — Enables/disables streaming of large transactions. + When set to `off`, streaming is disabled. When set to any other value, + large transactions are decoded while they're still in progress, and the + changes are sent to the downstream. If the value is set to `file`, + then the incoming changes of streaming transactions are stored in a file + and applied only after the transaction is committed on upstream. If the + value is set to `writer`, then the incoming changes are directly sent to + one of the writers, if available. If parallel apply is disabled or no + writer is free to handle streaming transaction, then the changes are + written to a file and applied after the transaction is committed. If the + value is set to `auto`, PGD tries to intelligently pick between + `file` and `writer`, depending on the transaction property and available + resources. You can't enable `streaming_mode` if the WAL + decoder is already enabled. + + For more details, see [Transaction streaming](../transaction-streaming). + +- `default_commit_scope` — The commit scope to use by default, + initially the `local` commit scope. This applies only to the + top-level node group. You can use individual rules for different + origin groups of the same commit scope. See + [Origin groups](../durability/commit-scopes/#origin-groups) for more details. + +### Notes + +This function passes a request to the group consensus mechanism to change +the defaults. The changes made are replicated globally using the consensus +mechanism. + +The function isn't transactional. The request is processed in the background +so you can't roll back the function call. Also, the changes might not be +immediately visible to the current transaction. + +This function doesn't hold any locks. + +!!! Warning + When you use this function to change the `apply_delay` value, the + change doesn't apply to nodes that are already members of the + group. + ## `bdr.alter_node_group_option` -Modify a PGD node group configuration. +Modify the PGD node group routing configuration. ### Synopsis @@ -27,25 +112,62 @@ bdr.alter_node_group_option(node_group_name text, - `config_value` — New value to be set for the given key. `config_value` will be parsed into the data type appropriate for the option. -Some parameters can be applied only to the top-level node group. For these parameters, the Groups column contains Top. Some parameters can be applied to the top-level node group and subgroups. For these parameters, the Groups column contains All. When a parameter can be applied only to subgroups, the Groups column contains Sub. - -The table shows the group options that can be changed using this function. - -| Name | Type | Groups | Description | -| ---- | ---- | ------ | ----------- | -| `apply_delay` | `interval` | All | How long nodes wait to apply incoming changes. This option is useful mainly to set up a special subgroup with delayed subscriber-only nodes. Don't set this on groups that contain data nodes or on the top-level group. Default is `0s`. | -| `check_constraints` | `boolean` | Top | Whether the apply process checks the constraints when writing replicated data. We recommend keeping the default value or you risk data loss. Valid values are `on` or `off`. Default is `on`. | -| `default_commit_scope` | `text` | All | The commit scope to use by default, initially the `local` commit scope. This option applies only to the top-level node group. You can use individual rules for different origin groups of the same commit scope. See [Origin groups](../durability/commit-scopes/#origin-groups) for more details. | -| `enable_proxy_routing` | `boolean` | All | Where [`pgd-proxy`](../routing/proxy) through the group leader is enabled for given group. Valid values are `on` or `off`. Default is `off`. | -| `enable_raft` | `boolean` | Sub | Whether group has its own Raft consensus. This option is necessary for setting `enable_proxy_routing` to `on`. This option is always `on` for the top-level group. Valid values are `on` or `off`. Default is `off` for subgroups. | -| `enable_wal_decoder` | `boolean` | Top | Enables/disables the decoding worker process. You can't enable the decoding worker process if `streaming_mode` is already enabled. Valid values are `on` or `off`. Default is `off`. | -| `location` | `text` | All | Information about group location. This option is purely metadata for monitoring. Default is `''` (empty string). | -| `num_writers` | `integer` | Top | Number of parallel writers for the subscription backing this node group. Valid values are `-1` or a positive integer. `-1` means the value specified by the GUC [`bdr.writers_per_subscription`](pgd-settings#bdrwriters_per_subscription) is used. `-1` is the default. | -| `route_reader_max_lag` | `integer` | All | Maximum lag in bytes for a node to be considered a viable read-only node. Currently reserved for future use. | -| `route_writer_max_lag` | `integer` | All | Maximum lag in bytes of the new write candidate to be selected as write leader. If no candidate passes this, no writer is selected automatically. Default is `-1`. | -| `route_writer_wait_flush` | `boolean` | All | Whether to switch if PGD needs to wait for the flush. Currently reserved for future use. | -| `streaming_mode` | `text` | Top | Enables/disables streaming of large transactions. When set to `off`, streaming is disabled. When set to any other value, large transactions are decoded while they're still in progress, and the changes are sent to the downstream. If the value is set to `file`, then the incoming changes of streaming transactions are stored in a file and applied only after the transaction is committed on upstream. If the value is set to `writer`, then the incoming changes are directly sent to one of the writers, if available.
If [parallel apply](../parallelapply) is disabled or no writer is free to handle streaming transactions, then the changes are written to a file and applied after the transaction is committed. If the value is set to `auto`, PGD tries to intelligently pick between `file` and `writer`, depending on the transaction property and available resources. You can't enable `streaming_mode` if the WAL decoder is already enabled. Default is `auto`.

For more details, see [Transaction streaming](../transaction-streaming). | - +Note that some parameters can only be applied to the top-level node group. + +The group options which can be changed using this function are: +- `apply_delay` (`interval`) — How long nodes wait to apply incoming + changes. This is useful mainly to setup a special sub-group with delayed + subscriber-only nodes. Don't set this on groups which contain data nodes or + on the top-level group. Default is `0s`. +- `check_constraints`(`boolean`) — Whether the apply process checks the + constraints when writing replicated data. It's recommended to keep this to + default value, otherwise you risk data loss. Valid values are either `on` or + `off`. Default is `on`. + This option can only be changed for the top-level node group. +- `default_commit_scope` (`text`) — The commit scope to use by default, + initially the `local` commit scope. This applies only to the + top-level node group. You can use individual rules for different + origin groups of the same commit scope. See + [Origin groups](../durability/commit-scopes/#origin-groups) for more details. +- `enable_proxy_routing`(`boolean`) — Where [`pgd-proxy`](../routing/proxy) + through the group leader is enabled for given group. Valid values are `on` or `off`. + Default is `off`. +- `enable_raft` (`boolean`) — Whether group has its own Raft consensus. This + is necessary for setting `enable_proxy_routing` to `on`. This is always `on` + for the top-level group. Valid values are `on` or `off`. Default is `off` for subgroups. +- `enable_wal_decoder` (`boolean`) — Enables/disables the decoding worker process. + You can't enable the decoding worker process if `streaming_mode` is already enabled. + Valid values are either `on` or `off`. Default is `off`. +- `location` (`text`) — Information about node location, this is purely metadata for + monitoring. Default is `''` (empty string). +- `num_writers` (`integer`) — Number of parallel writers for the subscription backing this + node group. Valid values are either `-1` or a positive integer. `-1` means the value + specified by the GUC [`bdr.writers_per_subscription`](pgd-settings#bdrwriters_per_subscription) + is used. `-1` is the default, + This option can only be changed for the top-level node group. +- `route_reader_max_lag` (`integer`) — Maximum lag in bytes for a node to be considered a viable + read-only node. Currently reserved for future use. +- `route_writer_max_lag` (`integer`) — Maximum lag in bytes of the new write candidate to be + selected as write leader. If no candidate passes this, no writer is + selected automatically. Default is `-1`. +- `route_writer_wait_flush` (`boolean`) — Whether to switch if we need to wait for the flush. + Currently reserved for future use. +- `streaming_mode` (`text`) — Enables/disables streaming of large transactions. + When set to `off`, streaming is disabled. When set to any other value, + large transactions are decoded while they're still in progress, and the + changes are sent to the downstream. If the value is set to `file`, + then the incoming changes of streaming transactions are stored in a file + and applied only after the transaction is committed on upstream. If the + value is set to `writer`, then the incoming changes are directly sent to + one of the writers, if available. If [parallel apply](../parallelapply) + is disabled or no writer is free to handle streaming transactions, then the + changes are written to a file and applied after the transaction is + committed. If the value is set to `auto`, PGD tries to intelligently pick + between `file` and `writer`, depending on the transaction property and + available resources. You can't enable `streaming_mode` if the WAL decoder + is already enabled. Default is `auto` + + For more details, see [Transaction streaming](../transaction-streaming). ### Return value @@ -255,10 +377,12 @@ bdr.create_node_group(node_group_name text, creating a subgroup means the local node won't join the new group, for example, when creating a independent remote group. In this case, you must specify `parent_group_name`. -- `node_group_type` — The valid values are `NULL` or `subscriber-only`. `NULL` (the default) is for creating a normal, general-purpose +- `node_group_type` — The valid values are `NULL`, `subscriber-only`, + and `shard`. `NULL` (the default) is for creating a normal, general-purpose node group. `subscriber-only` is for creating [subscriber-only groups](../node_management/subscriber_only/) whose members receive changes only from the fully joined nodes in the cluster but that never send changes to other nodes. + `shard` is reserved for future use. ### Notes @@ -489,57 +613,3 @@ bdr.wait_for_join_completion(verbose_progress boolean DEFAULT false) This function waits until the checks state of the local node reaches the target state, which was set by `bdr.create_node_group`, `bdr.join_node_group`, or `bdr.promote_node`. - - -## `bdr.alter_node_group_config` - -This function changes the configuration parameters of an existing PGD group. -Options with NULL value (default for all of them) aren't modified. - -!!! Warning - This function exists only for compatibility with PGD4 and 3.7. - Use [`bdr.alter_node_group_option`](#bdralter_node_group_option) instead. - -### Synopsis - -```sql -bdr.alter_node_group_config(node_group_name text, - insert_to_update boolean DEFAULT NULL, - update_to_insert boolean DEFAULT NULL, - ignore_redundant_updates boolean DEFAULT NULL, - check_full_tuple boolean DEFAULT NULL, - apply_delay interval DEFAULT NULL, - check_constraints boolean DEFAULT NULL, - num_writers int DEFAULT NULL, - enable_wal_decoder boolean DEFAULT NULL, - streaming_mode text DEFAULT NULL, - default_commit_scope text DEFAULT NULL) -``` - -### Parameters - -| Name | Description | -| ---- | ------------| -| `node_group_name` | Name of an existing PGD group. The local node must be part of the group. | -| `insert_to_update` | Reserved for backward compatibility. | -| `update_to_insert` | Reserved for backward compatibility. This option is deprecated and will be disabled or removed in future versions of PGD. Use `bdr.alter_node_set_conflict_resolver` instead. | -| `ignore_redundant_updates` | Reserved for backward compatibility. | -| `check_full_tuple` | Reserved for backward compatibility. | -| `apply_delay` | How long nodes wait to apply incoming changes. This parameter is useful mainly to set up a special subgroup with delayed subscriber-only nodes. Don't set this on groups that contain data nodes or on the top-level group. Default is `0s`. | -| `check_constraints` | Whether the apply process checks the constraints when writing replicated data. We recommend keeping this set to the default value or you risk data loss. Valid values are `on` or `off`. Default is `on`. Applies to top-level group only. | -| `num_writers` | Number of parallel writers for the subscription backing this node group. Valid values are `-1` or a positive integer. `-1` means the value specified by the GUC `bdr.writers_per_subscription` is used. `-1` is the default. Applies to top-level group only.| -| `enable_wal_decoder` | Enables/disables the decoding worker process. You can't enable the decoding worker process if `streaming_mode` is already enabled. Valid values are `on` or `off`. Default is `off`. Applies to top-level group only.| -| `streaming_mode` | Enables/disables streaming of large transactions. When set to `off`, streaming is disabled. When set to any other value, large transactions are decoded while they're still in progress, and the changes are sent to the downstream. If the value is set to `file`, then the incoming changes of streaming transactions are stored in a file and applied only after the transaction is committed on upstream. If the value is set to `writer`, then the incoming changes are directly sent to one of the writers, if available. If parallel apply is disabled or no writer is free to handle streaming transaction, then the changes are written to a file and applied after the transaction is committed. If the value is set to `auto`, PGD tries to intelligently pick between `file` and `writer`, depending on the transaction property and available resources. You can't enable `streaming_mode` if the WAL decoder is already enabled.

For more details, see [Transaction streaming](../transaction-streaming). Applies to top-level group only.| -| `default_commit_scope` | The commit scope to use by default, initially the `local` commit scope. This parameter applies only to the top-level node group. You can use individual rules for different origin groups of the same commit scope. See [Origin groups](../durability/commit-scopes/#origin-groups) for more details. | - -### Notes - -This function passes a request to the group consensus mechanism to change -the defaults. The changes made are replicated globally using the consensus -mechanism. - -The function isn't transactional. The request is processed in the background -so you can't roll back the function call. Also, the changes might not be -immediately visible to the current transaction. - -This function doesn't hold any locks. diff --git a/product_docs/docs/pgd/5/reference/routing.mdx b/product_docs/docs/pgd/5/reference/routing.mdx index 50c3e19933f..a91627bed1a 100644 --- a/product_docs/docs/pgd/5/reference/routing.mdx +++ b/product_docs/docs/pgd/5/reference/routing.mdx @@ -5,30 +5,26 @@ indexdepth: 3 rootisheading: false --- + + ### `bdr.create_proxy` -Create a proxy configuration. +Create a proxy #### Synopsis ```sql -bdr.create_proxy(proxy_name text, node_group text, proxy_mode text); +bdr.create_proxy(proxy_name text, node_group text); ``` #### Parameters -| Name | Type | Default | Description | -|--------------|------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `proxy_name` | text | | Name of the new proxy. | -| `node_group` | text | | Name of the group to be used by the proxy. | -| `proxy_mode` | text | `'default'` | Mode of the proxy. It can be `'default'` (listen_port connections follow write leader, no read_listen_port), `'read-only'` (no listen_port, read_listen_port connections follow read-only nodes), or `'any'` (listen_port connections follow write_leader, read_listen_port connections follow read-only nodes). Default is `'default'`. | - -When proxy_mode is set to `'default'`, all read options in the proxy config will be set to NULL. When it's set to `'read-only'`, all write options in the proxy config will be set to NULL. When set to `'any'` all options will be set to their defaults. - +- `proxy_name` — Name of the new proxy. +- `node_group` — Name of the group to be used by the proxy. ### `bdr.alter_proxy_option` -Change a proxy configuration +Change a proxy #### Synopsis @@ -38,37 +34,22 @@ bdr.alter_proxy_option(proxy_name text, config_key text, config_value text); #### Parameters -| Name | Type | Default | Description | -|----------------|------|---------|-----------------------------------------------| -| `proxy_name` | text | | Name of the proxy to be changed. | -| `config_key` | text | | Key of the option in the proxy to be changed. | -| `config_value` | text | | New value to be set for the given key. | - - -The table shows the proxy options (`config_key`) that can be changed using this function. - -| Option | Description | -|-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `listen_address` | Address for the proxy to listen on. Default is '{0.0.0.0}' | -| `listen_port` | Port for the proxy to listen on. Default is '6432' in 'default' or 'any' mode and '0' in 'read-only' mode which disables the write leader following port. | -| `max_client_conn` | Maximum number of connections for the proxy to accept. Default is '32767'. | -| `max_server_conn` | Maximum number of connections the proxy can make to the Postgres node. Default is '32767'. | -| `server_conn_timeout` | Connection timeout for server connections. Default is '2' (seconds). | -| `server_conn_keepalive` | Keepalive interval for server connections. Default is '10' (seconds). | -| `consensus_grace_period` | Duration for which proxy continues to route even upon loss of a Raft leader. If set to 0s, proxy stops routing immediately. Default is generally '6' (seconds) for local proxies and '12' (seconds) for global proxies. These values will be overridden if `raft_response_timeout`, `raft_global_election_timeout`, or `raft_group_election_timeout` are changed from their defaults. | -| `read_listen_address` | Address for the read-only proxy to listen on. Default is '{0.0.0.0}'. | -| `read_listen_port` | Port for the read-only proxy to listen on. Default is '6433' in 'read-only' or 'any' mode and '0' in 'default' mode which disables the read-only port . | -| `read_max_client_conn` | Maximum number of connections for the read-only proxy to accept. Default is '32767'. | -| `read_max_server_conn` | Maximum number of connections the read-only proxy can make to the Postgres node. Default is '32767'. | -| `read_server_conn_keepalive` | Keepalive interval for read-only server connections. Default is '10' (seconds). | -| `read_server_conn_timeout` | Connection timeout for read-only server connections. Default is '2' (seconds). | -| `read_consensus_grace_period` | Duration for which read-only proxy continues to route even upon loss of a Raft leader. Default is 1 hour. | - -Changing any of these values requires a restart of the proxy. +- `proxy_name` — Name of the proxy to be changed. +- `config_key` — Key of the option in the proxy to be changed. +- `config_value` — New value to be set for the given key. + +The proxy options that can be changed using this function are: +- `listen_address` — Address for the proxy to listen on. Default is '{0.0.0.0}'. +- `listen_port` — Port for the proxy to listen on. Default is '6432'. +- `max_client_conn` — Maximum number of connections for the proxy to accept. Default is '32767'. +- `max_server_conn` — Maximum number of connections the proxy can make to the Postgres node. Default is '32767'. +- `server_conn_timeout` — Connection timeout for server connections. Default is '2' (seconds). +- `server_conn_keepalive` — Keepalive interval for server connections. Default is '10' (seconds). +- `consensus_grace_period` — Duration for which proxy continues to route even upon loss of a Raft leader. If set to 0s, proxy stops routing immediately. Default is generally '6' (seconds) for local proxies and '12' (seconds) for global proxies. These values will be overriden if `raft_response_timeout`, `raft_global_election_timeout` or `raft_group_election_timeout` are changed from their defaults. ### `bdr.drop_proxy` -Drop a proxy configuration. +Drop a proxy #### Synopsis @@ -78,13 +59,11 @@ bdr.drop_proxy(proxy_name text); #### Parameters -| Name | Type | Default | Description | -|--------------|------|---------|-----------------------------------------------| -| `proxy_name` | text | | Name of the proxy to be dropped. | +- `proxy_name` — Name of the proxy to be dropped. ### `bdr.routing_leadership_transfer` -Changing the routing leader transfers the leadership of the node group to another node. +Changing the routing leader transfers the leadership of the node group to another node #### Synopsis @@ -97,10 +76,7 @@ bdr.routing_leadership_transfer(node_group_name text, #### Parameters -| Name | Type | Default | Description | -|--------------------|----------|----------|---------------------------------------------------------------------------------------------| -| `node_group_name` | text | | Name of group where the leadership transfer is requested. | -| `leader_name` | text | | Name of node that will become write leader. | -| `transfer_method` | text | `'strict'` | Type of the transfer. It can be `'fast'` or the default, `'strict'`, which checks the maximum lag. | -| `transfer_timeout` | interval | '10s' | Timeout of the leadership transfer. Default is 10 seconds. | - +- `node_group_name` — Name of group where the leadership transfer is requested. +- `leader_name` — Name of node that will become write leader. +- `transfer_method` — Type of the transfer, it can be "fast" or the default "strict" that checks the maximum lag. +- `transfer_timeout` — Timeout of the leadership transfer, default is 10 seconds. diff --git a/product_docs/docs/pgd/5/rel_notes/index.mdx b/product_docs/docs/pgd/5/rel_notes/index.mdx index a7cb7b6ac8f..f7851b087cb 100644 --- a/product_docs/docs/pgd/5/rel_notes/index.mdx +++ b/product_docs/docs/pgd/5/rel_notes/index.mdx @@ -3,7 +3,6 @@ title: "EDB Postgres Distributed release notes" navTitle: "Release notes" description: "Release notes for EDB Postgres Distributed" navigation: -- pgd_5.5.0_rel_notes - pgd_5.4.1_rel_notes - pgd_5.4.0_rel_notes - pgd_5.3.0_rel_notes @@ -23,13 +22,12 @@ provide information on what was new in each release. For new functionality introduced in a minor or patch release, the content also indicates the release that introduced the feature. -| Release Date | EDB Postgres Distributed | BDR extension | PGD CLI | PGD Proxy | -|--------------|------------------------------|---------------|---------|-----------| -| 16 May 2024 | [5.5.0](pgd_5.5.0_rel_notes) | 5.5.0 | 5.5.0 | 5.5.0 | +| Release Date | EDB Postgres Distributed | BDR extension | PGD CLI | PGD Proxy | +| ------------- | ---------------------------- | ------------- | ------- | --------- | | 03 Apr 2024 | [5.4.1](pgd_5.4.1_rel_notes) | 5.4.1 | 5.4.0 | 5.4.0 | | 05 Mar 2024 | [5.4.0](pgd_5.4.0_rel_notes) | 5.4.0 | 5.4.0 | 5.4.0 | | 14 Nov 2023 | [5.3.0](pgd_5.3.0_rel_notes) | 5.3.0 | 5.3.0 | 5.3.0 | -| 04 Aug 2023 | [5.2.0](pgd_5.2.0_rel_notes) | 5.2.0 | 5.2.0 | 5.2.0 | +| 04 Aug 2023 | [5.2.0](pgd_5.2.0_rel_notes) | 5.2.0 | 5.2.0 | 5.2.0 | | 16 May 2023 | [5.1.0](pgd_5.1.0_rel_notes) | 5.1.0 | 5.1.0 | 5.1.0 | | 21 Mar 2023 | [5.0.1](pgd_5.0.1_rel_notes) | 5.0.0 | 5.0.1 | 5.0.1 | | 21 Feb 2023 | [5.0.0](pgd_5.0.0_rel_notes) | 5.0.0 | 5.0.0 | 5.0.0 | diff --git a/product_docs/docs/pgd/5/rel_notes/pgd_5.5.0_rel_notes.mdx b/product_docs/docs/pgd/5/rel_notes/pgd_5.5.0_rel_notes.mdx deleted file mode 100644 index e9309f22365..00000000000 --- a/product_docs/docs/pgd/5/rel_notes/pgd_5.5.0_rel_notes.mdx +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: "EDB Postgres Distributed 5.5.0 release notes" -navTitle: "Version 5.5.0" ---- - -Released: 16 May 2024 - -EDB Postgres Distributed version 5.5.0 is a minor version of EDB Postgres Distributed. - -!!! Important Recommended upgrade -We recommend that all users of PGD 5 upgrade to PGD 5.5. See [PGD/TPA upgrades](../upgrades/tpa_overview) for details. -!!! - - -## Highlights of EDB Postgres Distributed 5.5.0 - -Highlights of this 5.5.0 release include: - -* Read scalability enhancements in PGD Proxy which allow read-only queries to be routed to nodes that aren't the write leader. This feature can improve the overall performance of the cluster. - -## Compatibility - -!!! Note EDB server version compatibility -This version requires the recently released Postgres versions 14.10, 15.4, -or 16.1 (or later) of EDB Postgres Advanced Server or EDB Postgres Extended -Server. No such restrictions exist for Community Postgres Server. - -Package managers on Debian, RHEL, and SLES pull in the required EDB Postgres -Advanced Server or EDB Postgres Extended upgrades with an upgrade of EDB -Postgres Distributed. -!!! - -## Features - -| Component | Version | Description | Addresses | -|-----------|---------|------------------------------------------------------------------------------------------------|-----------| -| BDR | 5.5.0 | Added support for read-only proxy routing. | | -| BDR | 5.5.0 | Improve stability of routing leader selection by using Raft heartbeat for connectivity check. | | -| CLI | 5.5.0 | Added PGD CLI binaries for macOS. | | -| Proxy | 5.5.0 | Added support for read-only proxy routing. | | - - -## Enhancements - -| Component | Version | Description | Addresses | -|-----------|---------|--------------------------------------------------------------------------------------------------------------------------------|----------------| -| BDR | 5.5.0 | Improved bulk INSERT/UPDATE/DELETE performance by sending multiple messages together in a group rather than individually. | | -| BDR | 5.5.0 | Changes received by the writer as now not saved to a temporary file. | | -| BDR | 5.5.0 | BDR now logs completion of an extension upgrade. | | -| BDR | 5.5.0 | Added restrictions for group commit options. | | -| BDR | 5.5.0 | Each autopartition task is now executed in its own transaction. | RT101407/35476 | -| BDR | 5.5.0 | DETACH CONCURRENTLY is now used to drop partitions. | RT101407/35476 | -| BDR | 5.5.0 | Node group creation on a node bad state is now disallowed. | | -| BDR | 5.5.0 | Granted additional object permissions to role `bdr_read_all_stats`. | | -| BDR | 5.5.0 | Improve stability of manager worker and Raft consensus by not throwing error on non-fatal dynamic shared memory read failures. | | -| BDR | 5.5.0 | Improved stability of Raft consensus and workers by handling dynamic shared memory errors in the right place. | | -| BDR | 5.5.0 | The number of changes processed by writer in a large transaction is now exposed. | | -| BDR | 5.5.0 | Heartbeat timings in Raft are now exposed in `get_raft_status()`. | | -| BDR | 5.5.0 | Follower information in Raft is now exposed in `get_raft_status()` on Raft leader nodes. | | -| BDR | 5.5.0 | BDR now exposes the number of changes processed by writer in a large transaction. | | -| BDR | 5.5.0 | `bdr_init_physical` now stops the initial replication connection and starts it only when needed. | RT102828/35305 | -| BDR | 5.5.0 | `bdr_superuser` is now granted use of `pg_file_settings` and `pg_show_all_file_settings()`. | | -| CLI | 5.5.0 | Added new read scalability related options to JSON output of `show-proxies ` and `show-groups` commands. | | -| CLI | 5.5.0 | Added new option called `proxy-mode` to `create-proxy` command for read scalability support. | | -| CLI | 5.5.0 | Added raft leader in tabular output of `show-groups` command. | | - - -## Bug fixes - -| Component | Version | Description | Addresses | -|-----------|---------|------------------------------------------------------------------------------------------------------------------------------|----------------| -| BDR | 5.5.0 | Improved handling of node group configuration parameter "check_constraints". | RT99956/31896 | -| BDR | 5.5.0 | Fixed incorrect parsing of pre-commit message that caused nodes to diverge on commit decision for group commit transactions. | | -| BDR | 5.5.0 | Prevent potential segfault in `bdr.monitor_group_versions()` | RT102290/34051 | -| BDR | 5.5.0 | BDR now correctly elects a new leader when the current leader gets route_writes turned off. | | -| BDR | 5.5.0 | `bdr.remove_commit_scope()` now handles non-existent commit scope. | | -| BDR | 5.5.0 | An improved queue flush process now prevents unexpected writer terminations. | RT98966/35447 | -| BDR | 5.5.0 | Fixed multi-row conflict accidentally deleting the wrong tuple multiple times . | | -| BDR | 5.5.0 | Fixed receiver to send status update when writer is blocked, avoiding slot disconnect. | | -| BDR | 5.5.0 | Fix minor memory leak during `bdr_join_node_group_sql`. | | -| BDR | 5.5.0 | Node joining with witness and standby nodes as source nodes is now disallowed. | | -| BDR | 5.5.0 | Use `bdr.default_sequence_kind` when updating sequence kind of existing sequences upon node creation. | | -| BDR | 5.5.0 | Fixed a bug preventing some trusted extension management commands (CREATE/ALTER) from being replicated. | | -| BDR | 5.5.0 | Fixed a non-critical segfault which could occur in upgrades from BDR 3.7. | | -| BDR | 5.5.0 | Manage rights elevation for trusted extensions | | - - diff --git a/product_docs/docs/pgd/5/routing/administering.mdx b/product_docs/docs/pgd/5/routing/administering.mdx deleted file mode 100644 index e8863e2419f..00000000000 --- a/product_docs/docs/pgd/5/routing/administering.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Administering PGD Proxy -navTitle: Administering ---- - -## Switching the write leader - -Switching the write leader is a manual operation that you can perform to change the node that's the write leader. -It can be useful when you want to perform maintenance on the current write leader node or when you want to change the write leader for any other reason. -When changing write leader, there are two modes, `strict` and `fast`. -In `strict` mode, the lag is checked before switching the write leader. It will wait until the lag is less than `route_writer_max_lag` before starting the switchover. This is the default. -In `fast` mode, the write leader is switched immediately. -You can also set a timeout parameter to specify the time to wait for the switchover to complete. - -!!! Note - The switchover operation is not a guaranteed operation. If, due to a timeout or for other reasons, the switchover to the given target node fails, PGD may elect another node as write leader in its place. This other node can include the current write leader node. PGD will always try to elect a new write leader if the switchover operation fails. -!!! - -### Using SQL - -You can perform a switchover operation that explicitly changes the node that's -the write leader to another node. - -Use the [`bdr.routing_leadership_transfer()`](/pgd/latest/reference/routing#bdrrouting_leadership_transfer) function. - -For example, to switch the write leader to node `node1` in group `group1`, use the following SQL command: - -```sql -SELECT bdr.routing_leadership_transfer('group1', 'node1','strict','10s'); -``` -This command switches the write leader using `strict` mode and waits for up to 10 seconds for the switchover to complete. Those are default settings, so you can omit them. - -```sql -SELECT bdr.routing_leadership_transfer('group1', 'node1'); -``` - -### Using PGD CLI - -You can use the [`switchover`](/pgd/latest/cli/command_ref/pgd_switchover/) command to perform a switchover operation. - -For example, to switch the write leader from node `node1` to node `node2` in group `group1`, use the following command: - -```sh -pgd switchover --node-group group1 --node-name node1 --method strict --timeout 10s -``` - -This command switches the write leader using `strict` mode and waits for up to 10 seconds for the switchover to complete. Those are default settings, so you can omit them. - -```sh -pgd switchover --node-group group1 --node-name node1 -``` diff --git a/product_docs/docs/pgd/5/routing/configuration.mdx b/product_docs/docs/pgd/5/routing/configuration.mdx deleted file mode 100644 index 151a46d7bb3..00000000000 --- a/product_docs/docs/pgd/5/routing/configuration.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "PGD Proxy configuration" -navTitle: "Configuration" ---- - -## Group-level configuration - -Configuring the routing is done through either SQL interfaces or through -PGD CLI. - -You can enable routing decisions by calling the [`bdr.alter_node_group_option()`](/pgd/latest/reference/nodes-management-interfaces#bdralter_node_group_option) function. -For example: - -```text -SELECT bdr.alter_node_group_option('region1-group', 'enable_proxy_routing', 'true') -``` - -You can disable it by setting the same option to `false`. - -Additional group-level options affect the routing decisions: - -- `route_writer_max_lag` — Maximum lag in bytes of the new write candidate to be - selected as write leader. If no candidate passes this, no writer is - selected automatically. -- `route_reader_max_lag` — Maximum lag in bytes for a node to be considered a viable - read-only node (PGD 5.5.0 and later). - -## Node-level configuration - -Set per-node configuration of routing using [`bdr.alter_node_option()`](/pgd/latest/reference/nodes-management-interfaces#bdralter_node_option). The -available options that affect routing are: - -- `route_dsn` — The dsn used by proxy to connect to this node. -- `route_priority` — Relative routing priority of the node against other nodes in - the same node group. Used only when electing a write Leader. -- `route_fence` — Determines whether the node is fenced from routing. When fenced, the node can't receive connections - from PGD Proxy. It therefore can't become the write Leader or be available in the read-only node pool. -- `route_writes` — Determines whether writes can be routed to this node, that is, whether the node - can become write leader. -- `route_reads` — Determines whether read-only connections can be routed to this node (PGD 5.5.0 and later). - -## Proxy-level configuration - -You can configure the proxies using SQL interfaces. - -### Creating and dropping proxy configurations - -You can add a proxy configuration using [`bdr.create_proxy`](/pgd/latest/reference/routing#bdrcreate_proxy). -For example, `SELECT bdr.create_proxy('region1-proxy1', 'region1-group');` -creates the default configuration for a proxy named `region1-proxy1` in the PGD group `region1-group`. - -The name of the proxy given here must be same as the name given in the proxy configuration file. - -You can remove a proxy configuration using `SELECT bdr.drop_proxy('region1-proxy1')`. -Dropping a proxy deactivates it. - -### Altering proxy configurations - -You can configure options for each proxy using the [`bdr.alter_proxy_option()`](/pgd/latest/reference/routing#bdralter_proxy_option) function. - -The available options are: - -- `listen_address` — Address for the proxy to listen on. -- `listen_port` — Port for the proxy to listen on. -- `max_client_conn` — Maximum number of connections for the proxy to accept. -- `max_server_conn` — Maximum number of connections the proxy can make to the - Postgres node. -- `server_conn_timeout` — Connection timeout for server connections. -- `server_conn_keepalive` — Keepalive interval for server connections. -- `consensus_grace_period` — Duration for which proxy continues to route even upon loss -of a Raft leader. If set to `0s`, proxy stops routing immediately. -- `read_listen_address` — Address for the read-only proxy to listen on. -- `read_listen_port` — Port for the read-only proxy to listen on. -- `read_max_client_conn` — Maximum number of connections for the read-only proxy to accept. -- `read_max_server_conn` — Maximum number of connections the read-only proxy can make to the - Postgres node. -- `read_server_conn_keepalive` — Keepalive interval for read-only server connections. -- `read_server_conn_timeout` — Connection timeout for read-only server connections. -- `read_consensus_grace_period` — Duration for which read-only proxy continues to route even upon loss of a Raft leader. diff --git a/product_docs/docs/pgd/5/routing/index.mdx b/product_docs/docs/pgd/5/routing/index.mdx index 27308c310ab..8601350c100 100644 --- a/product_docs/docs/pgd/5/routing/index.mdx +++ b/product_docs/docs/pgd/5/routing/index.mdx @@ -1,30 +1,88 @@ --- -title: "PGD Proxy" -navTitle: "PGD Proxy" +title: "Application connection management" +navTitle: "Connection management" indexCards: none description: How to use PGD Proxy to maintain consistent connections to the PGD cluster. navigation: - proxy - installing_proxy - - configuration - - administering - - monitoring - - readonly - raft --- -Managing application connections is an important part of high availability. PGD Proxy offers a way to manage connections to the EDB Postgres Distributed cluster. It acts as a proxy layer between the client application and the Postgres database. +Managing application connections is an important part of high availability. -* [PGD Proxy overview](/pgd/latest/routing/proxy) provides an overview of the PGD Proxy, its processes, and how it interacts with the EDB Postgres Distributed cluster. +Especially with asynchronous replication, having a consistent write lead node is +important to avoid conflicts and guarantee availability for the +application. -* [Installing the PGD Proxy service](/pgd/latest/routing/installing_proxy) covers installation of the PGD Proxy service on a host. +EDB Postgres Distributed provides a proxy layer called PGD Proxy, which is +normally installed in highly available configuration (at least two instances per +region). -* [Configuring PGD Proxy](/pgd/latest/routing/configuration) details the three levels (group, node, and proxy) of configuration on a cluster that control how the PGD Proxy service behaves. +The PGD Proxy connects to one of the EDB Postgres Distributed nodes and monitors +routing configuration changes as decided by the EDB Postgres Distributed cluster. +It ensures that the connections are routed to the correct nodes consistently. -* [Administering PGD Proxy](/pgd/latest/routing/administering) shows how to switch the write leader and manage the PGD Proxy. +## Configuration -* [Monitoring PGD Proxy](/pgd/latest/routing/monitoring) looks at how to monitor PGD Proxy through the cluster and at a service level. +Configuring the routing is done through either SQL interfaces or through +PGD-CLI. -* [Read-only routing](/pgd/latest/routing/readonly) explains how the read-only routing feature in PGD Proxy enables read scalability. +You can enable routing decisions by calling the `bdr.alter_node_group_option()` function. +For example: -* [Raft](/pgd/latest/routing/raft) provides an overview of the Raft consensus mechanism used to coordinate PGD Proxy. +```text +SELECT bdr.alter_node_group_option('region1-group', 'enable_proxy_routing', 'true') +``` + +You can disable it by setting the same option to `false`. + +Additional group-level options affect the routing decisions: + +- `route_writer_max_lag` — Maximum lag in bytes of the new write candidate to be + selected as write leader. If no candidate passes this, no writer is + selected automatically. +- `route_reader_max_lag` — Maximum lag in bytes for a node to be considered a viable + read-only node. Currently reserved for future use. + +Per-node configuration of routing is set using `bdr.alter_node_option()`. The +available options that affect routing are the following: + +- `route_dsn` — The dsn used by proxy to connect to this node. +- `route_priority` — Relative routing priority of the node against other nodes in + the same node group. +- `route_fence` — Whether the node is fenced from routing, that is, it can't receive connections + from PGD Proxy. +- `route_writes` — Whether writes can be routed to this node, that is, whether the node + can become write leader. +- `route_reads` — Whether read-only connections can be routed to this node. Currently + reserved for future use. + +You can also configure the proxies using SQL interfaces. You can add proxy configuration +using `bdr.create_proxy`. For example, `SELECT bdr.create_proxy('region1-proxy1', 'region1-group');` +adds the default configuration for a proxy named `region1-proxy1` that's a member +of PGD group `region1-group`. The name of the proxy given here must be same +as the name given in the proxy configuration file. You can remove a proxy configuration +using `SELECT bdr.drop_proxy('region1-proxy1')`. The proxy is +deactivated as a result. + +You can configure options for each proxy using the `bdr.alter_proxy_option()` function. +The available options are: + +- `listen_address` — Address for the proxy to listen on. +- `listen_port` — Port for the proxy to listen on. +- `max_client_conn` — Maximum number of connections for the proxy to accept. +- `max_server_conn` — Maximum number of connections the proxy can make to the + Postgres node. +- `server_conn_timeout` — Connection timeout for server connections. +- `server_conn_keepalive` — Keepalive interval for server connections. +- `consensus_grace_period` — Duration for which proxy continues to route even upon loss +of a Raft leader. If set to `0s`, proxy stops routing immediately. + +The current configuration of every group is visible in the +`bdr.node_group_routing_config_summary` view. Similarly, the +`bdr.node_routing_config_summary` view shows current per-node routing +configuration. `bdr.proxy_config_summary` shows per-proxy configuration. + +You can also do a switchover operation to explicitly change the node that's +the write leader. To do so, use the `bdr.routing_leadership_transfer()` function. diff --git a/product_docs/docs/pgd/5/routing/installing_proxy.mdx b/product_docs/docs/pgd/5/routing/installing_proxy.mdx index bb031e8c6a1..971b6105e29 100644 --- a/product_docs/docs/pgd/5/routing/installing_proxy.mdx +++ b/product_docs/docs/pgd/5/routing/installing_proxy.mdx @@ -33,9 +33,9 @@ log-level: debug cluster: name: cluster-name endpoints: - - "host=bdr-a1 port=5432 dbname=bdrdb user=pgdproxy" - - "host=bdr-a3 port=5432 dbname=bdrdb user=pgdproxy" - - "host=bdr-a2 port=5432 dbname=bdrdb user=pgdproxy" + - "host=bdr-a1 port=5432 dbname=bdrdb user=pgdproxy " + - "host=bdr-a3 port=5432 dbname=bdrdb user=pgdproxy " + - "host=bdr-a2 port=5432 dbname=bdrdb user=pgdproxy " proxy: name: "proxy-a1" ``` diff --git a/product_docs/docs/pgd/5/routing/monitoring.mdx b/product_docs/docs/pgd/5/routing/monitoring.mdx deleted file mode 100644 index 497fddfa9e5..00000000000 --- a/product_docs/docs/pgd/5/routing/monitoring.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Monitoring PGD Proxy -navTitle: Monitoring ---- - -Proxies can be monitored at the cluster and group level or at the process level. - -## Monitoring through the cluster - -### Using SQL - -The current configuration of every group is visible in the [`bdr.node_group_routing_config_summary`](/pgd/latest/reference/catalogs-internal#bdrnode_group_routing_config_summary) view. - -The [`bdr.node_routing_config_summary`](/pgd/latest/reference/catalogs-internal#bdrnode_routing_config_summary) view shows current per-node routing configuration. - -[`bdr.proxy_config_summary`](/pgd/latest/reference/catalogs-internal#bdrproxy_config_summary) shows per-proxy configuration. - -### Using PGD CLI - -You can use the `show-proxies` command to view the current status of all proxies in the PGD cluster. -Use the `show-proxy` command to view the status of a specific proxy. - -## Monitoring at the process level - -### Proxy health check - -PGD Proxy provides the following HTTP(s) health check API endpoints. The API endpoints respond to `GET` requests. You need to enable and configure the endpoints before using them. See [Configuration](installing_proxy#configuring-health-check). - -| Endpoint | Description | -| --- | --- | -| `/health/is-ready` | Checks if the proxy can successfully route connections to the current write leader. | -| `/health/is-live` | Checks if the proxy is running. | -| `/health/is-write-ready` | Checks if the proxy can successfully route connections to the current write leader (PGD 5.5.0 and later). | -| `/health/is-read-only-ready` | Checks if the proxy can successfully route read-only connections (PGD 5.5.0 and later). | - -#### Readiness - -On receiving a valid `GET` request: - -* When in default (write) mode, the proxy checks if it can successfully route connections to the current write leader. -* When in read-only mode, the proxy checks if it can successfully route read-only connections. -* When in any mode, the proxy first checks if it can successfully route connections to the current write leader. If it can, the check is successful. If not, it checks if it can route a read-only connection. If it can, the check is successful. If not, the check fails. - -If the check returns successfully, the API responds with a body containing `true` and an HTTP status code `200 (OK)`. Otherwise, it returns a body containing `false` with the HTTP status code `500 (Internal Server Error)`. - -#### Liveness - -Liveness checks return either `true` with HTTP status code `200 (OK)` or an error. They never return `false` because the HTTP server listening for the request is stopped if the PGD Proxy service fails to start or exits. - -## Proxy log location - -Proxies also write logs to system logging where they can be monitored with other system services. - -### syslog - -- Debian based - `/var/log/syslog` -- Red Hat based - `/var/log/messages` - -Use the `journalctl` command to filter and view logs for troubleshooting PGD Proxy. The following are sample commands for quick reference: - -```sh -journalctl -u pgd-proxy -n100 -f -journalctl -u pgd-proxy --since today -journalctl -u pgd-proxy --since "10 min ago" -journalctl -u pgd-proxy --since "2022-10-20 16:21:50" --until "2022-10-20 16:21:55" -``` \ No newline at end of file diff --git a/product_docs/docs/pgd/5/routing/proxy.mdx b/product_docs/docs/pgd/5/routing/proxy.mdx index 0b1736eb39d..66373ec1456 100644 --- a/product_docs/docs/pgd/5/routing/proxy.mdx +++ b/product_docs/docs/pgd/5/routing/proxy.mdx @@ -1,108 +1,97 @@ --- -title: "EDB Postgres Distributed Proxy overview" -navTitle: "PGD Proxy overview" -indexCards: simple +title: "EDB Postgres Distributed Proxy" +navTitle: "PGD Proxy" +indexCards: none +navigation: +- installing_proxy + directoryDefaults: - description: "The PGD Proxy service acts as a proxy layer between the client application and Postgres for your PGD cluster." + description: "The PGD Proxy is a service that acts as proxy layer between the client application and Postgres for your EDB Postgres Distributed cluster" --- +EDB Postgres Distributed Proxy is a daemon that acts as an abstraction layer between the client application and Postgres. It interfaces with the PGD consensus mechanism to get the identity of the current write leader node and redirects traffic to that node. -Especially with asynchronous replication, having a consistent write leader node is -important to avoid conflicts and guarantee availability for the application. - -The two parts to EDB Postgres Distributed's proxy layer are: - -* Proxy configuration and routing information, which is maintained by the PGD consensus mechanism. -* The PGD Proxy service, which is installed on a host. It connects to the PGD cluster, where it reads its configuration and listens for changes to the routing information. - -This is normally installed in highly available configuration (at least two instances of the proxy service per PGD group). +The PGD cluster always has at least one global group and one data group. PGD elects the write leader for each data group that has the `enable_proxy_routing` and `enable_raft` options set to true. You can attach Proxy to a global group or data group. You can attach multiple proxies to each group. -Once configured, the PGD Proxy service monitors routing changes as decided by the EDB Postgres Distributed cluster. It acts on these changes to ensure that connections are consistently routed to the correct nodes. +PGD Proxy is a TCP layer 4 proxy. -Configuration changes to the PGD Proxy service are made through the PGD cluster. -The PGD Proxy service reads its configuration from the PGD cluster, but the proxy service must be restarted to apply those changes. +## How it works -The information about currently selected write and read nodes is visible in -`bdr.node_group_routing_summary`. This is node-local view: the proxy -always reads from Raft leader to get a current and consistent view. +Upon starting, PGD Proxy connects to one of the endpoints given in the local config file. It fetches: -## Leader selection +- DB connection information for all nodes +- Proxy options like listen address, listen port +- Routing details like current write leader -The write leader is selected by the current Raft leader (either subgroup one or top-level group one, -depending on whether the leader for the subgroup or the cluster's top-level group is being selected). +Endpoints given in the config file are used only at startup. After that, actual endpoints are taken from the PGD catalog's `route_dsn` field in `bdr.node_routing_config_summary`. -Leader is selected from candidate nodes that are reachable and meet the criteria based -on the configuration as described in [PGD Proxy cluster configuration](#pgd-proxy-cluster-configuration). To be a viable candidate, the node must have -`route_writes` enabled and `route_fence` disabled and be within `route_writer_max_lag` -(if enabled) from the previous leader. The candidates are ordered by their `route_priority` -in descending order and by the lag from the previous leader in ascending order. -The new leader selection process is started either when there's no existing leader currently -(this could be because there were no valid candidates or because Raft was down) or when -connectivity is lost to the existing leader. +PGD manages write leader election. PGD Proxy interacts with PGD to get write leader change events notifications on Postgres notify/listen channels and routes client traffic to the current write leader. PGD Proxy disconnects all existing client connections on write leader change or when write leader is unavailable. Write leader election is a Raft-backed activity and is subject to Raft leader availability. PGD Proxy closes the new client connections if write leader is unavailable. -A node is considered connected if the last Raft protocol message received from the leader -isn't older than Raft election timeout -(see [Internal settings - Raft timeouts](../reference/pgd-settings#internal-settings---raft-timeouts)). +PGD Proxy responds to write leader change events that can be categorized into two modes of operation: *failover* and *switchover*. -Since the Raft leader is sending heartbeat 3 times every election timeout limit, the leader -node needs to miss the reply to 3 heartbeats before it's considered disconnected. +Automatic transfer of write leadership from the current write leader node to a new node in the event of Postgres or operating system crash is called failover. PGD elects a new write leader when the current write leader goes down or becomes unresponsive. Once the new write leader is elected by PGD, PGD Proxy closes existing client connections to the old write leader and redirects new client connections to the newly elected write leader. -## PGD Proxy cluster configuration +User-controlled, manual transfer of write leadership from the current write leader to a new target leader is called switchover. Switchover is triggered through the [PGD CLI switchover](../cli/command_ref/pgd_switchover) command. The command is submitted to PGD, which attempts to elect the given target node as the new write leader. Similar to failover, PGD Proxy closes existing client connections and redirects new client connections to the newly elected write leader. This is useful during server maintenance, for example, if the current write leader node needs to be stopped for maintenance like a server update or OS patch update. -The PGD cluster always has at least one top-level group and one data group. PGD elects the write leader for each data group that has the `enable_proxy_routing` and `enable_raft` options set to true. +### Consensus grace period -The cluster also maintains Proxy configurations for each group. Each configuration has a name and is associated with a group. You can attach Proxy to a top-level group or data group. You can attach multiple proxies to each group. +PGD Proxy provides the `consensus_grace_period` proxy option that can be used to configure the routing behavior upon loss of a Raft leader. PGD Proxy continues to route to the current write leader (if it's available) for this duration. If the new Raft leader isn't elected during this period, the proxy stops routing. If set to `0s`, PGD Proxy stops routing immediately. -When a PGD Proxy service starts running on a host, it has a name in its local configuration file and it connects to a node in a group. From there, it uses the name to look up its complete configuration as stored on the group. +The main purpose of this option is to allow users to configure the write behavior when the Raft leader is lost. When the Raft leader isn't present in the cluster, it's not always guaranteed that the current write leader seen by the proxy is the correct one. In some cases, like network partition in the following example, it is possible that the two write leaders may be seen by two different proxies attached to the same group increasing the chances of write conflicts. If this isn't the desired behavior, then the previously mentioned `consensus_grace_period` can be set to 0s. This setting configures the proxy to stop routing and closes existing open connections immediately when it detects the Raft leader is lost. -## PGD Proxy service +#### Network partition example -The EDB Postgres Distributed Proxy (PGD Proxy) service is a process that acts as an abstraction layer between the client application and Postgres. It interfaces with the PGD consensus mechanism to get the identity of the current write leader node and redirects traffic to that node. It also optionally supports a read-only mode where it can route read-only queries to nodes that aren't the write leader, improving the overall performance of the cluster. +Consider a 3-data node group with a proxy on each data node. In this case, if the current write leader gets network partitioned or isolated, then the data nodes present in the majority partition elects a new write leader. If `consensus_grace_period` is set to a non-zero value, say `10s`, then the proxy present on the previous write leader continues to route writes for this duration. -PGD Proxy is a TCP layer 4 proxy. +In this case, if the grace period is kept too high, then writes continue to happen on the two write leaders. This condition increases the chances of write conflicts. -## How they work together +Having said that, most of the time, upon loss of the current Raft leader, the new Raft leader gets elected by BDR within a few seconds if more than half of the nodes (quorum) are still up. Hence, if the Raft leader is down but the write leader is still up, then proxy can be configured to allow routing by keeping `consensus_grace_period` to a non-zero, positive value. The proxy waits for the Raft leader to get elected during this period before stopping routing. This might be helpful in some cases where availability is more important. -Upon starting, PGD Proxy connects to one of the endpoints given in the local config file. It fetches: +### Multi-host connection strings -- DB connection information for all nodes -- Proxy options like listen address, listen port -- Routing details including the current write leader in default mode, read nodes in read-only mode, or both in any mode. +The PostgreSQL C client library (libpq) allows you to specify multiple host names in a single connection string for simple failover. This is also supported by client libraries (drivers) in some other programming languages. It works well for failing over across PGD Proxy instances that are down or inaccessible. -The endpoints given in the config file are used only at startup. After that, actual endpoints are taken from the PGD catalog's `route_dsn` field in [`bdr.node_routing_config_summary`](/pgd/latest/reference/catalogs-internal#bdrnode_routing_config_summary). +However, if the PGD Proxy instance is accessible but doesn't have access to the write leader, or the write leader for a given instance doesn't exist (that is, because there's no write leader for the given PGD group), the connection simply fails. No other hosts in the multi-host connection string is tried. This behavior is consistent with the behavior of PostgreSQL client libraries with other proxies like HAProxy or pgbouncer. -PGD manages write leader election. PGD Proxy interacts with PGD to get write leader change events notifications on Postgres notify/listen channels and routes client traffic to the current write leader. PGD Proxy disconnects all existing client connections on write leader change or when write leader is unavailable. Write leader election is a Raft-backed activity and is subject to Raft leader availability. PGD Proxy closes the new client connections if the write leader is unavailable. +## Managing PGD Proxy -PGD Proxy responds to write leader change events that can be categorized into two modes of operation: *failover* and *switchover*. +PGD CLI provides a few commands to manage proxies in a PGD cluster, such as `create-proxy`, `delete-proxy`, `set-proxy-options`, and `show-proxies`. See [PGD CLI](../cli/command_ref) for more information. -Automatic transfer of write leadership from the current write leader node to a new node in the event of Postgres or operating system crash is called *failover*. PGD elects a new write leader when the current write leader goes down or becomes unresponsive. Once the new write leader is elected by PGD, PGD Proxy closes existing client connections to the old write leader and redirects new client connections to the newly elected write leader. +See [Connection management](../routing) for more information on the PGD side of configuration and management of PGD Proxy. -User-controlled, manual transfer of write leadership from the current write leader to a new target leader is called *switchover*. Switchover is triggered through the [PGD CLI switchover](../cli/command_ref/pgd_switchover) command. The command is submitted to PGD, which attempts to elect the given target node as the new write leader. Similar to failover, PGD Proxy closes existing client connections and redirects new client connections to the newly elected write leader. This is useful during server maintenance, for example, if the current write leader node needs to be stopped for maintenance like a server update or OS patch update. +### Proxy health check -If the proxy is configured to support read-only routing, it can route read-only queries to a pool of nodes that are not the write leader. The pool of nodes is maintained by the PGD cluster and proxies listen for changes to the pool. When the pool changes, the proxy updates its routing configuration and starts routing read-only queries to the new pool of nodes and disconnecting existing client connections to nodes that have left the pool. +PGD Proxy provides the following HTTP(s) health check API endpoints. The API endpoints respond to `GET` requests. You need to enable and configure them before using them. See [Configurations](installing_proxy#configuring-health-check). -### Consensus grace period -PGD Proxy provides the `consensus_grace_period` proxy option that can be used to configure the routing behavior upon loss of a Raft leader. PGD Proxy continues to route to the current write leader (if it's available) for this duration. If the new Raft leader isn't elected during this period, the proxy stops routing. If set to `0s`, PGD Proxy stops routing immediately. +``` +GET /health/is-ready +GET /health/is-live +``` -The main purpose of this option is to allow users to configure the write behavior when the Raft leader is lost. When the Raft leader isn't present in the cluster, it's not always guaranteed that the current write leader seen by the proxy is the correct one. In some cases, like network partition in the following example, it's possible that the two write leaders may be seen by two different proxies attached to the same group, increasing the chances of write conflicts. If this isn't the behavior you want, then you can set the previously mentioned `consensus_grace_period` to 0s. This setting configures the proxy to stop routing and closes existing open connections immediately when it detects the Raft leader is lost. +#### Readiness -#### Network partition example +On receiving a valid `GET` request, the proxy checks if it can successfully route connections to the current write leader. If the check returns successfully, the API responds with a body containing `true` and an HTTP status code `200 (OK)`. Otherwise, it returns a body containing `false` with the HTTP status code `500 (Internal Server Error)`. -Consider a 3-data node group with a proxy on each data node. In this case, if the current write leader gets network partitioned or isolated, then the data nodes present in the majority partition elect a new write leader. If `consensus_grace_period` is set to a non-zero value, say `10s`, then the proxy present on the previous write leader continues to route writes for this duration. -In this case, if the grace period is kept too high, then writes continue to happen on the two write leaders. This condition increases the chances of write conflicts. +#### Liveness -Having said that, most of the time, upon loss of the current Raft leader, the new Raft leader gets elected by BDR within a few seconds if more than half of the nodes (quorum) are still up. Hence, if the Raft leader is down but the write leader is still up, then proxy can be configured to allow routing by keeping `consensus_grace_period` to a non-zero, positive value. The proxy waits for the Raft leader to get elected during this period before stopping routing. This might be helpful in some cases where availability is more important. +Liveness checks return either `true` with HTTP status code `200 (OK)` or an error. They never return `false` because the HTTP server listening for the request is stopped if the PGD Proxy service fails to start or exits. -### Read consensus grace period +## Proxy log location -Similar to the `consensus_grace_period`, a `read_consensus_grace_period` option is available for read-only routing. This option can be used to configure the routing behavior upon loss of a Raft leader for read-only queries. PGD Proxy continues to route to the current read nodes for this duration. If the new Raft leader isn't elected during this period, the proxy stops routing read-only queries. If set to `0s`, PGD Proxy stops routing read-only queries immediately. +### syslog -### Multi-host connection strings +- Debian based - `/var/log/syslog` +- Red Hat based - `/var/log/messages` -The PostgreSQL C client library (libpq) allows you to specify multiple host names in a single connection string for simple failover. This is also supported by client libraries (drivers) in some other programming languages. It works well for failing over across PGD Proxy instances that are down or inaccessible. +Use the `journalctl` command to filter and view logs for troubleshooting Proxy. The following are few sample commands for quick reference: -However, if the PGD Proxy instance is accessible but doesn't have access to the write leader, or the write leader for a given instance doesn't exist (that is, because there's no write leader for the given PGD group), the connection simply fails. No other hosts in the multi-host connection string is tried. This behavior is consistent with the behavior of PostgreSQL client libraries with other proxies like HAProxy or pgbouncer. +```sh +journalctl -u pgd-proxy -n100 -f +journalctl -u pgd-proxy --since today +journalctl -u pgd-proxy --since "10 min ago" +journalctl -u pgd-proxy --since "2022-10-20 16:21:50" --until "2022-10-20 16:21:55" +``` diff --git a/product_docs/docs/pgd/5/routing/readonly.mdx b/product_docs/docs/pgd/5/routing/readonly.mdx deleted file mode 100644 index 1245d1929e1..00000000000 --- a/product_docs/docs/pgd/5/routing/readonly.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: Read-only routing with PGD Proxy -navTitle: Read-only routing ---- - -## Background - -By default, PGD Proxy routes connections to the currently selected write leader in the cluster. This allows the write traffic conflicts to be rapidly and consistently resolved. Just routing everything to a single node, the write leader, is a natural fit for traditional high availability deployments where system throughput is typically limited to the throughput of what a single node can handle. - -But for some use cases, this behavior also means that clients that are only querying the data are also placing a load on the current write leader. It's possible this writer leader could be equally well served by one of the non-write leader nodes in the cluster. - -If you could move traffic that was read-only queries to the non-write leader nodes, you could, at least in theory, handle a throughput which could be a multiple of a single nodes capability. -An approach like this would, though, usually require changes to applications so that they were aware of details of cluster topology and the current node status to detect the write leader. - -## Read-only routing in PGD Proxy - -From PGD 5.5.0, PGD Proxy addresses this requirement to utilize read capacity while minimizing application exposure to the cluster status. It does this by offering a new `read_listen_port` on proxies that complement the existing listen port. Proxies can be configured with either or both of these ports. - -When a proxy is configured with a `read_listen_port`, connections to that particular port are routed to available data nodes that aren't the current write leader. If an application only queries and reads from the database, using a `read_listen_port` ensures that your queries aren't answered by the write leader. - -Because PGD Proxy is a TCP Layer 4 proxy, it doesn't interfere with traffic passing through it. That means that it can't detect attempts to write passing through the `read_listen_port` connections. As it can't distinguish between a SELECT or an INSERT, it's possible to write through a read-only port. - -The active-active nature of PGD means that any write operation will be performed and replicated, and conflict resolution may or may not have to take place. It's up to the application to avoid this and make sure that it uses only `read_listen_ports` for read-only traffic. - -Where available, the problem can be mitigated on the client side by passing [`default_transaction_read_only=on`](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-DEFAULT-TRANSACTION-READ-ONLY) in the connection string or equivalent for the driver in use. - -### Valid read-only nodes - -Only data nodes that aren't the write leader are valid as read-only nodes. For reference, the following node types aren't eligible to be a read-only node: - -* Witness nodes can't be eligible because they don't contain data. -* Logical standbys can't be eligible because they're standbys and prioritize replicating. -* Subscriber-only nodes also aren't currently eligible. - -## Creating a proxy configuration - -Proxy creation functions in PGD take an optional `proxy-mode` parameter. This parameter can be set to one of the following values: -* `default`: This is the default value. It creates a proxy that can handles traffic that follows the write leader on port 6432. -* `read-only`: This option creates a read-only proxy that routes traffic to nodes that aren't the write leader. It handles this read-only traffic only on port 6433. -* `any`: This option creates create a proxy that can handle both read-only and write-leader-following traffic on separate ports: 6432 for write-leader-following traffic and 6433 for read-only traffic. - -### Creating a Read-Only Proxy - -#### Using SQL - -To create a new read-only proxy, use the `bdr.create_proxy` function. - -```sql -SELECT bdr.create_proxy('proxy-ro1','group-a','read-only'); -``` - -This command creates a read-only proxy named `proxy-ro1` in group `group-a`. By default, it listens on port 6433 for read-only traffic. - -#### Using PGD CLI - -To create a new read-only proxy, use the `pgd create-proxy` command with the optional `--proxy_mode` flag set to `read-only`. - -```sh -pgd create-proxy --proxy-name proxy-ro1 --node-group group-a --proxy-mode read-only -``` - -## Configuring running proxies - -!!! Note -To change a proxy's configuration, the proxy must be restarted after changes are made. -!!! - -Activating read-only routing on a proxy is done by setting the `read_listen_port` option to a port number. This port number is the port on which the proxy will listen for read-only traffic. -If the proxy already has a listen_port set, then the proxy will listen on both ports, routing read/write and read-only traffic respectively on each port. -This is equivalent to creating a proxy with `proxy-mode` set to `any`. - -If you set a `read_listen_port` on a proxy and then set the `listen_port` to 0, the proxy listens only on the `read_listen_port` and routes only read-only traffic. -This is equivalent to creating a proxy with `proxy-mode` set to `read-only`. -The configuration elements related to the read/write port will be cleared (set to null). - -If you set a `listen_port` on a proxy and then set the `read_listen_port` to 0, the proxy listens only on the `listen_port` and routes only read/write traffic. -This is equivalent to creating a proxy with `proxy-mode` set to `default`. -The configuration elements related to the read-only port will be cleared (set to null). - - -### Configuring using SQL - -To configure a read-only proxy port on a proxy, use the `bdr.alter_proxy_options` function. - -```sql -SELECT bdr.alter_proxy_options('proxy-a1','read_listen_port','6433'); -``` - -This command configures a read-only proxy port on port 6433 in the proxy-a1 configuration. - -To remove the read-only proxy, set the port to 0. - -```sql -SELECT bdr.alter_proxy_options('proxy-a1','read_listen_port','0'); -``` - -### Configuring using PGD CLI - -To configure a read-only proxy port on a proxy, use the `pgd alter-proxy` command: - -```sh -pgd set-proxy-options --proxy-name proxy-a1 --option read_listen_port=6433 -``` - -This command configures a read-only proxy port on port 6433 in the proxy-a1 configuration. - -To remove the read-only proxy, set the port to 0: - -```sh -pgd set-proxy-options --proxy-name proxy-a1 --option read_listen_port=0 -```