diff --git a/product_docs/docs/pgd/5.6/commit-scopes/camo.mdx b/product_docs/docs/pgd/5.6/commit-scopes/camo.mdx index fb5269bf609..63db329783b 100644 --- a/product_docs/docs/pgd/5.6/commit-scopes/camo.mdx +++ b/product_docs/docs/pgd/5.6/commit-scopes/camo.mdx @@ -96,7 +96,7 @@ This example considers a setup with two PGD nodes that are the CAMO partner of e ```sql -- create a CAMO commit scope for a group over -- a definite pair of nodes -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'camo_dc', rule := 'ALL (left_dc) CAMO DEGRADE ON (timeout=500ms) TO ASYNC' diff --git a/product_docs/docs/pgd/5.6/commit-scopes/commit-scopes.mdx b/product_docs/docs/pgd/5.6/commit-scopes/commit-scopes.mdx index d4f5ce82787..5471e91d108 100644 --- a/product_docs/docs/pgd/5.6/commit-scopes/commit-scopes.mdx +++ b/product_docs/docs/pgd/5.6/commit-scopes/commit-scopes.mdx @@ -44,10 +44,10 @@ A commit scope will not be used if it is not local and the node where the commit ## Creating a Commit Scope -Use `bdr.add_commit_scope` to add our example rule to a commit scope. For example: +Use `bdr.create_commit_scope` to add our example rule to a commit scope. For example: ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'example_bdr_group', rule := 'MAJORITY (example_bdr_group) GROUP COMMIT', @@ -65,7 +65,7 @@ The rule will then be evaluated. If the rule mentions groups that don't exist or Once the rule is added, the commit scope will be available for use. -The `wait_for_ready` controls whether the `bdr.add_commit_scope()` call blocks until the rule has been added to the relevant nodes. The setting defaults to true and can be omitted. +The `wait_for_ready` controls whether the `bdr.create_commit_scope()` call blocks until the rule has been added to the relevant nodes. The setting defaults to true and can be omitted. ## Using a commit scope diff --git a/product_docs/docs/pgd/5.6/commit-scopes/group-commit.mdx b/product_docs/docs/pgd/5.6/commit-scopes/group-commit.mdx index 74fb4231bec..c90fff4973a 100644 --- a/product_docs/docs/pgd/5.6/commit-scopes/group-commit.mdx +++ b/product_docs/docs/pgd/5.6/commit-scopes/group-commit.mdx @@ -19,7 +19,7 @@ the transaction has been flushed to disk and is visible to all other transaction ## Example ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'left_dc', rule := 'ALL (left_dc) GROUP COMMIT(commit_decision=raft) AND ANY 1 (right_dc) GROUP COMMIT', @@ -191,7 +191,7 @@ COMMIT; In this case, the `eager_scope` commit scope is defined something like this: ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'eager_scope', origin_node_group := 'top_group', rule := 'ALL (top_group) GROUP COMMIT (conflict_resolution = eager, commit_decision = raft) ABORT ON (timeout = 60s)', diff --git a/product_docs/docs/pgd/5.6/commit-scopes/lag-control.mdx b/product_docs/docs/pgd/5.6/commit-scopes/lag-control.mdx index 0d3886453d8..8bfad64a166 100644 --- a/product_docs/docs/pgd/5.6/commit-scopes/lag-control.mdx +++ b/product_docs/docs/pgd/5.6/commit-scopes/lag-control.mdx @@ -108,13 +108,13 @@ SELECT bdr.create_node_group( The following code adds Lag Control rules for those two data centers, using individual rules for each subgroup: ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'left_dc', rule := 'ALL (left_dc) LAG CONTROL (max_commit_delay=500ms, max_lag_time=30s) AND ANY 1 (right_dc) LAG CONTROL (max_commit_delay=500ms, max_lag_time=30s)', wait_for_ready := true ); -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'right_dc', rule := 'ANY 1 (left_dc) LAG CONTROL (max_commit_delay=0.250ms, max_lag_size=100MB) AND ALL (right_dc) LAG CONTROL (max_commit_delay=0.250ms, max_lag_size=100MB)', diff --git a/product_docs/docs/pgd/5.6/commit-scopes/origin_groups.mdx b/product_docs/docs/pgd/5.6/commit-scopes/origin_groups.mdx index 9b298559d67..0b5fbab6748 100644 --- a/product_docs/docs/pgd/5.6/commit-scopes/origin_groups.mdx +++ b/product_docs/docs/pgd/5.6/commit-scopes/origin_groups.mdx @@ -21,13 +21,13 @@ SELECT bdr.create_node_group( -- create a commit scope with individual rules -- for each sub-group -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'left_dc', rule := 'ALL (left_dc) GROUP COMMIT (commit_decision=raft) AND ANY 1 (right_dc) GROUP COMMIT', wait_for_ready := true ); -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'right_dc', rule := 'ANY 1 (left_dc) GROUP COMMIT AND ALL (right_dc) GROUP COMMIT (commit_decision=raft)', @@ -63,13 +63,13 @@ This can make certain commit scopes rules like those above in `example_scope`, e For example, again suppose that for transactions originating from nodes in `right_dc` you want all nodes in `right_dc` to confirm and any 1 from `left_dc` to confirm before the transaction is committed. Also, again suppose that for transactions originating in `left_dc` you want all nodes in `left_dc` and any 1 in `right_dc` to confirm before the transaction is commited. Above we used these two rules for this when defining `example_scope`: ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'left_dc', rule := 'ALL (left_dc) GROUP COMMIT (commit_decision=raft) AND ANY 1 (right_dc) GROUP COMMIT', wait_for_ready := true ); -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'right_dc', rule := 'ANY 1 (left_dc) GROUP COMMIT AND ALL (right_dc) GROUP COMMIT (commit_decision=raft)', @@ -80,7 +80,7 @@ SELECT bdr.add_commit_scope( However, with `ORIGIN_GROUP`, just adding and using the following single-rule commit scope, `example_scope_2`, will have the same effect as the two individual rules we used above in `example_scope`: ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope_2', origin_node_group := 'top_group', rule := 'ALL ORIGIN_GROUP GROUP COMMIT (commit_decision=raft) AND ANY 1 NOT ORIGIN_GROUP GROUP COMMIT'; diff --git a/product_docs/docs/pgd/5.6/commit-scopes/synchronous_commit.mdx b/product_docs/docs/pgd/5.6/commit-scopes/synchronous_commit.mdx index 3b853d7729a..f39a6e66271 100644 --- a/product_docs/docs/pgd/5.6/commit-scopes/synchronous_commit.mdx +++ b/product_docs/docs/pgd/5.6/commit-scopes/synchronous_commit.mdx @@ -17,7 +17,7 @@ Unlike other commit scope kinds, such as `GROUP COMMIT` and `CAMO`, the transact In this example, when this commit scope is in use, any node in the `left_dc` group uses `SYNCHRONOUS_COMMIT` to replicate changes to the other nodes in the `left_dc` group. It looks for a majority of nodes in the `left_dc` group to confirm that they committed the transaction. ``` -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_sc_scope', origin_node_group := 'left_dc', rule := 'MAJORITY (left_dc) SYNCHRONOUS_COMMIT', diff --git a/product_docs/docs/pgd/5.6/known_issues.mdx b/product_docs/docs/pgd/5.6/known_issues.mdx index 5eae2cd0fe8..a6aad74ae7b 100644 --- a/product_docs/docs/pgd/5.6/known_issues.mdx +++ b/product_docs/docs/pgd/5.6/known_issues.mdx @@ -47,7 +47,6 @@ Make sure that any transactions using a specific commit scope have finished befo - The [PGD CLI](cli) can return stale data on the state of the cluster if it's still connecting to nodes that were previously parted from the cluster. Edit the [`pgd-cli-config.yml`](cli/configuring_cli/#using-a-configuration-file) file, or change your [`--dsn`](cli/configuring_cli/#using-database-connection-strings-in-the-command-line) 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 that 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). - Tables configured with `REPLICA IDENTITY FULL` and include `box`, `polygon` or `json` types in their columns are using PGD aren't able to be replicated. diff --git a/product_docs/docs/pgd/5.6/reference/commit-scopes.mdx b/product_docs/docs/pgd/5.6/reference/commit-scopes.mdx index c1582ccfcf6..1c2c7378946 100644 --- a/product_docs/docs/pgd/5.6/reference/commit-scopes.mdx +++ b/product_docs/docs/pgd/5.6/reference/commit-scopes.mdx @@ -11,9 +11,9 @@ Commit scopes are rules that determine how transaction commits and conflicts are You can manipulate commit scopes using the following functions: -- [`bdr.add_commit_scope`](/pgd/latest/reference/functions#bdradd_commit_scope) +- [`bdr.create_commit_scope`](/pgd/latest/reference/functions#bdrcreate_commit_scope) - [`bdr.alter_commit_scope`](/pgd/latest/reference/functions#bdralter_commit_scope) -- [`bdr.remove_commit_scope`](/pgd/latest/reference/functions#bdrremove_commit_scope) +- [`bdr.drop_commit_scope`](/pgd/latest/reference/functions#bdrdrop_commit_scope) ## Commit scope syntax @@ -70,7 +70,7 @@ ALL ORIGIN_GROUP SYNCHRONOUS_COMMIT DEGRADE ON (timeout = 10s) TO MAJORITY ORIGI Instead of targeting a specific group, you can also use `ORIGIN_GROUP`, which dynamically refers to the bottommost group from which a transaction originates. Therefore, if you have a top level group, `top_group`, and two subgroups as children, `left_dc` and `right_dc`, then adding a commit scope like: ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'example_scope', origin_node_group := 'top_level_group', rule := 'MAJORITY ORIGIN_GROUP SYNCHRONOUS_COMMIT', diff --git a/product_docs/docs/pgd/5.6/reference/functions.mdx b/product_docs/docs/pgd/5.6/reference/functions.mdx index 350a46ba0af..c7ff9881a58 100644 --- a/product_docs/docs/pgd/5.6/reference/functions.mdx +++ b/product_docs/docs/pgd/5.6/reference/functions.mdx @@ -1128,20 +1128,28 @@ The client must be prepared to retry the function call on error. ### `bdr.add_commit_scope` -`bdr.add_commit_scope` creates a rule for the given commit scope name and origin node group. If the rule is the same for all nodes in the EDB Postgres Distributed cluster, invoking this function once for the top-level node group is enough to fully define the commit scope. +**Deprecated**. Use [`bdr.create_commit_scope`](/pgd/5.6/reference/functions#bdrcreate_commit_scope) instead. Previously, this function was used to add a commit scope to a node group. It's now deprecated and will emit a warning until it is removed in a future release, at which point it will raise an error. + +### `bdr.create_commit_scope` + +`bdr.create_commit_scope` creates a rule for the given commit scope name and origin node group. If the rule is the same for all nodes in the EDB Postgres Distributed cluster, invoking this function once for the top-level node group is enough to fully define the commit scope. Alternatively, you can invoke it multiple times with the same `commit_scope_name` but different origin node groups and rules for commit scopes that vary depending on the origin of the transaction. #### Synopsis ```sql -bdr.add_commit_scope( +bdr.create_commit_scope( commit_scope_name NAME, origin_node_group NAME, rule TEXT, wait_for_ready boolean DEFAULT true) ``` +#### Note + +`bdr.create_commit_scope` replaces the deprecated [`bdr.add_commit_scope`](/pgd/5.6/reference/functions#bdradd_commit_scope) function. Unlike `add_commit_scope`, it does not silently overwrite existing commit scopes when the same name is used. Instead, an error is reported. + ### `bdr.alter_commit_scope` `bdr.alter_commit_scope` allows you to change a specific rule for a single origin node group in a commit scope. @@ -1155,25 +1163,21 @@ bdr.alter_commit_scope( rule TEXT) ``` -#### Note - -When using `bdr.add_commit_scope`, if a new commit scope is added that 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` +### `bdr.drop_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. #### Synopsis ```sql -bdr.remove_commit_scope( +bdr.drop_commit_scope( commit_scope_name NAME, origin_node_group NAME) ``` !!! Note - Removing a commit scope that's still used as default by a node group isn't allowed. + Dropping a commit scope that's still used as default by a node group isn't allowed. + +### `bdr.remove_commit_scope` + +**Deprecated**. Use [`bdr.drop_commit_scope`](/pgd/5.6/reference/functions#bdrdrop_commit_scope) instead. Previously, this function was used to remove a commit scope from a node group. It's now deprecated and will emit a warning until it is removed in a future release, at which point it will raise an error. diff --git a/product_docs/docs/pgd/5.6/reference/index.json b/product_docs/docs/pgd/5.6/reference/index.json index a102cffe597..bef1d9c6d28 100644 --- a/product_docs/docs/pgd/5.6/reference/index.json +++ b/product_docs/docs/pgd/5.6/reference/index.json @@ -115,7 +115,9 @@ "bdrcamo_transactions_resolved": "/pgd/5.6/reference/functions#bdrcamo_transactions_resolved", "bdrlogical_transaction_status": "/pgd/5.6/reference/functions#bdrlogical_transaction_status", "bdradd_commit_scope": "/pgd/5.6/reference/functions#bdradd_commit_scope", + "bdrcreate_commit_scope": "/pgd/5.6/reference/functions#bdrcreate_commit_scope", "bdralter_commit_scope": "/pgd/5.6/reference/functions#bdralter_commit_scope", + "bdrdrop_commit_scope": "/pgd/5.6/reference/functions#bdrdrop_commit_scope", "bdrremove_commit_scope": "/pgd/5.6/reference/functions#bdrremove_commit_scope", "bdrdefault_conflict_detection": "/pgd/5.6/reference/pgd-settings#bdrdefault_conflict_detection", "bdrdefault_sequence_kind": "/pgd/5.6/reference/pgd-settings#bdrdefault_sequence_kind", diff --git a/product_docs/docs/pgd/5.6/reference/index.mdx b/product_docs/docs/pgd/5.6/reference/index.mdx index 7612375d274..a35a63d0a51 100644 --- a/product_docs/docs/pgd/5.6/reference/index.mdx +++ b/product_docs/docs/pgd/5.6/reference/index.mdx @@ -162,7 +162,9 @@ The reference section is a definitive listing of all functions, views, and comma * [`bdr.logical_transaction_status`](functions#bdrlogical_transaction_status) ### [Commit Scope functions](functions#commit-scope-functions) * [`bdr.add_commit_scope`](functions#bdradd_commit_scope) + * [`bdr.create_commit_scope`](functions#bdrcreate_commit_scope) * [`bdr.alter_commit_scope`](functions#bdralter_commit_scope) + * [`bdr.drop_commit_scope`](functions#bdrdrop_commit_scope) * [`bdr.remove_commit_scope`](functions#bdrremove_commit_scope) diff --git a/product_docs/docs/pgd/5.6/upgrades/compatibility.mdx b/product_docs/docs/pgd/5.6/upgrades/compatibility.mdx index d1ef52660d1..ac30086652a 100644 --- a/product_docs/docs/pgd/5.6/upgrades/compatibility.mdx +++ b/product_docs/docs/pgd/5.6/upgrades/compatibility.mdx @@ -29,7 +29,7 @@ The `global` scope no longer exists. To create scope with the same behavior, use [Group Commit](../commit-scopes/group-commit). ```sql -SELECT bdr.add_commit_scope( +SELECT bdr.create_commit_scope( commit_scope_name := 'eager_scope', origin_node_group := 'top_group', rule := 'ALL (top_group) GROUP COMMIT (conflict_resolution = eager, commit_decision = raft) ABORT ON (timeout = 60s)',