Merge pull request #6251 from EnterpriseDB/docs/pgd/fix/add-to-create…

…-commit-scope

Switched add_commit_scope to create_commit_scope and added reference notes

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'

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

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)',

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)',

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';

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',

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. 

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',

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.

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",

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)
 
 

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)',