From bfbd3d1c1afc3fc4139c3760811ba06ff0670ae9 Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan Date: Mon, 8 Apr 2024 10:59:40 +0100 Subject: [PATCH 1/6] First pass at adding permission notes to features Signed-off-by: Dj Walker-Morgan --- product_docs/docs/pgd/5/durability/camo.mdx | 6 ++++++ product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx | 2 ++ product_docs/docs/pgd/5/sequences.mdx | 6 ++++++ product_docs/docs/pgd/5/striggers.mdx | 6 ++++++ 4 files changed, 20 insertions(+) diff --git a/product_docs/docs/pgd/5/durability/camo.mdx b/product_docs/docs/pgd/5/durability/camo.mdx index cd91ef3ecb5..bf43905cf15 100644 --- a/product_docs/docs/pgd/5/durability/camo.mdx +++ b/product_docs/docs/pgd/5/durability/camo.mdx @@ -217,6 +217,12 @@ If status of the transaction wasn't success or connection was bad, we check if t ### Working with the CAMO partner +!!! Note Permissions Required +A number of the following CAMO functions require permission. Any user wishing to use CAMO, +the user must have at least the [bdr_application](../security/pgd-predefined-roles/#bdr_application) +role assigned to them. +!!! + The function [`bdr.is_camo_partner_connected()`](/pgd/latest/reference/functions#bdris_camo_partner_connected) allows checking the connection status of a CAMO partner node configured in pair mode. There currently is no equivalent for CAMO used with Eager Replication. To check that the CAMO partner is ready, use the function [`bdr.is_camo_partner_ready`](/pgd/latest/reference/functions#bdris_camo_partner_ready). Underneath, this triggers the switch to and from local mode. diff --git a/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx b/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx index d3620bee230..c8d1a01d31d 100644 --- a/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx +++ b/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx @@ -149,4 +149,6 @@ required to read the conflict history. If it's useful to have a user that can see conflicts for all tables, you can optionally grant the role bdr_read_all_conflicts to that user. +## Adding a role to a user + diff --git a/product_docs/docs/pgd/5/sequences.mdx b/product_docs/docs/pgd/5/sequences.mdx index a64bc3a03b7..f153aad0260 100644 --- a/product_docs/docs/pgd/5/sequences.mdx +++ b/product_docs/docs/pgd/5/sequences.mdx @@ -18,6 +18,12 @@ produce values that are unique only on the local node. This is important because unique ids generated by such sequences cause conflict and data loss by means of discarded `INSERT` actions in multi-master replication. +!!! Note Permissions Required +PGD global sequences are on by default. This means that for any user to use sequences, +the user must have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) +role assigned to them. +!!! + ## PGD global sequences For this reason, PGD provides an application-transparent way to generate unique diff --git a/product_docs/docs/pgd/5/striggers.mdx b/product_docs/docs/pgd/5/striggers.mdx index 44f83ea29cd..6e8fddd89fc 100644 --- a/product_docs/docs/pgd/5/striggers.mdx +++ b/product_docs/docs/pgd/5/striggers.mdx @@ -13,6 +13,12 @@ data processing on the downstream/target node: Together, these types of triggers are known as *stream triggers*. +!!! Note Permissions Required +Stream triggers are a PGD feature which requires permission. Any user wishing to use triggers, +the user must have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) +role assigned to them. +!!! + Stream triggers are designed to be trigger-like in syntax. They leverage the PostgreSQL BEFORE trigger architecture and are likely to have similar performance characteristics as PostgreSQL BEFORE Triggers. From b58fbe30ee25f2067793ab5210bdfe5b094381de Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan Date: Mon, 8 Apr 2024 11:24:15 +0100 Subject: [PATCH 2/6] Removed adding section Signed-off-by: Dj Walker-Morgan --- product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx | 3 --- 1 file changed, 3 deletions(-) diff --git a/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx b/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx index c8d1a01d31d..a48810a9827 100644 --- a/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx +++ b/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx @@ -149,6 +149,3 @@ required to read the conflict history. If it's useful to have a user that can see conflicts for all tables, you can optionally grant the role bdr_read_all_conflicts to that user. -## Adding a role to a user - - From 7fb17b8f2bae969d6c5132404cdc6acfce2c9cb4 Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan Date: Mon, 8 Apr 2024 14:13:12 +0100 Subject: [PATCH 3/6] More notes, edited index, linked more bdr_application Signed-off-by: Dj Walker-Morgan --- .../5/consistency/column-level-conflicts.mdx | 4 ++++ product_docs/docs/pgd/5/consistency/crdt.mdx | 4 ++++ .../pgd/5/reference/functions-internal.mdx | 20 ++++++++++++------- product_docs/docs/pgd/5/reference/index.json | 2 ++ product_docs/docs/pgd/5/reference/index.mdx | 2 ++ .../pgd/5/security/pgd-predefined-roles.mdx | 14 ++++++------- product_docs/docs/pgd/5/striggers.mdx | 10 +++++----- 7 files changed, 37 insertions(+), 19 deletions(-) diff --git a/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx b/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx index 08274942963..2a472d9ad3d 100644 --- a/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx +++ b/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx @@ -35,6 +35,10 @@ Column-level conflict resolution requires the table to have `REPLICA IDENTITY FU ## Enabling and disabling column-level conflict resolution +!!! Note Permissions Required +Column level conflict detection uses the `column_timestamp` type. This requires the user to have have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) role assigned to them. +!!! + The [bdr.alter_table_conflict_detection()](conflicts#bdralter_table_conflict_detection) function manages column-level conflict resolution. ### Example diff --git a/product_docs/docs/pgd/5/consistency/crdt.mdx b/product_docs/docs/pgd/5/consistency/crdt.mdx index 9794d02ca8c..26c228388d1 100644 --- a/product_docs/docs/pgd/5/consistency/crdt.mdx +++ b/product_docs/docs/pgd/5/consistency/crdt.mdx @@ -7,6 +7,10 @@ redirects: Conflict-free replicated data types (CRDT) support merging values from concurrently modified rows instead of discarding one of the rows as traditional resolution does. +!!! Note Permissions Required +PGD CRDT require execute access to CRDT types, therefore a user must have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) role assigned to them. +!!! + Each CRDT type is implemented as a separate PostgreSQL data type with an extra callback added to the `bdr.crdt_handlers` catalog. The merge process happens inside the PGD writer on the apply side without any user action needed. diff --git a/product_docs/docs/pgd/5/reference/functions-internal.mdx b/product_docs/docs/pgd/5/reference/functions-internal.mdx index 04c038af82d..0f6c8f222f5 100644 --- a/product_docs/docs/pgd/5/reference/functions-internal.mdx +++ b/product_docs/docs/pgd/5/reference/functions-internal.mdx @@ -367,17 +367,23 @@ Currently, row_filters are ignored by this function. The `bdr.resynchronize_table_from_node` function can be executed only by the owner of the table, provided the owner has bdr_superuser privileges. -### `bdr.seq_nextval` +### `bdr.seq_currval` -Internal implementation of sequence increments. +Part of the internal implementation of global sequence manipulation. -Use this function instead of standard `nextval` in queries that -interact with [PGD global sequences](../sequences/#pgd-global-sequences). +Invoked automatically as needed. -#### Notes +### `bdr.seq_lastval` + +Part of the internal implementation of global sequence manipulation. + +Invoked automatically as needed. + +### `bdr.seq_nextval` + +Part of the internal implementation of global sequence increments. -The following are also internal PGD sequence manipulation functions. -`bdr.seq_currval` and `bdr.seq_lastval` are used automatically. +Invoked automatically as needed. ### `bdr.show_subscription_status` diff --git a/product_docs/docs/pgd/5/reference/index.json b/product_docs/docs/pgd/5/reference/index.json index fea21e7af4b..cfbe6393bb9 100644 --- a/product_docs/docs/pgd/5/reference/index.json +++ b/product_docs/docs/pgd/5/reference/index.json @@ -309,6 +309,8 @@ "bdrreset_relation_stats": "/pgd/latest/reference/functions-internal#bdrreset_relation_stats", "bdrreset_subscription_stats": "/pgd/latest/reference/functions-internal#bdrreset_subscription_stats", "bdrresynchronize_table_from_node": "/pgd/latest/reference/functions-internal#bdrresynchronize_table_from_node", + "bdrseq_currval": "/pgd/latest/reference/functions-internal#bdrseq_currval", + "bdrseq_lastval": "/pgd/latest/reference/functions-internal#bdrseq_lastval", "bdrseq_nextval": "/pgd/latest/reference/functions-internal#bdrseq_nextval", "bdrshow_subscription_status": "/pgd/latest/reference/functions-internal#bdrshow_subscription_status", "bdrshow_workers": "/pgd/latest/reference/functions-internal#bdrshow_workers", diff --git a/product_docs/docs/pgd/5/reference/index.mdx b/product_docs/docs/pgd/5/reference/index.mdx index 70d1e1b6d15..a9d766b5371 100644 --- a/product_docs/docs/pgd/5/reference/index.mdx +++ b/product_docs/docs/pgd/5/reference/index.mdx @@ -423,6 +423,8 @@ The reference section is a definitive listing of all functions, views and comman * [`bdr.reset_relation_stats`](functions-internal#bdrreset_relation_stats) * [`bdr.reset_subscription_stats`](functions-internal#bdrreset_subscription_stats) * [`bdr.resynchronize_table_from_node`](functions-internal#bdrresynchronize_table_from_node) + * [`bdr.seq_currval`](functions-internal#bdrseq_currval) + * [`bdr.seq_lastval`](functions-internal#bdrseq_lastval) * [`bdr.seq_nextval`](functions-internal#bdrseq_nextval) * [`bdr.show_subscription_status`](functions-internal#bdrshow_subscription_status) * [`bdr.show_workers`](functions-internal#bdrshow_workers) diff --git a/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx b/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx index a48810a9827..db7e46756bd 100644 --- a/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx +++ b/product_docs/docs/pgd/5/security/pgd-predefined-roles.mdx @@ -117,22 +117,22 @@ EXECUTE privilege on: - [`bdr.create_conflict_trigger`](/pgd/latest/reference/streamtriggers/interfaces#bdrcreate_conflict_trigger) - [`bdr.create_transform_trigger`](/pgd/latest/reference/streamtriggers/interfaces#bdrcreate_transform_trigger) - [`bdr.drop_trigger`](/pgd/latest/reference/streamtriggers/interfaces#bdrdrop_trigger) -- `bdr.get_configured_camo_partner` +- [`bdr.get_configured_camo_partner`](/pgd/latest/reference/functions#bdrget_configured_camo_partner) - [`bdr.global_lock_table`](/pgd/latest/reference/functions#bdrglobal_lock_table) -- `bdr.is_camo_partner_connected` -- `bdr.is_camo_partner_ready` -- `bdr.logical_transaction_status` +- [`bdr.is_camo_partner_connected`](/pgd/latest/reference/functions#bdris_camo_partner_connected) +- [`bdr.is_camo_partner_ready`](/pgd/latest/reference/functions#bdris_camo_partner_ready) +- [`bdr.logical_transaction_status`](/pgd/latest/reference/functions#bdrlogical_transaction_status) - `bdr.ri_fkey_trigger` - [`bdr.seq_nextval`](/pgd/latest/reference/functions-internal#bdrseq_nextval) -- `bdr.seq_currval` -- `bdr.seq_lastval` +- [`bdr.seq_currval`](/pgd/latest/reference/functions-internal#bdrseq_currval) +- [`bdr.seq_lastval`](/pgd/latest/reference/functions-internal#bdrseq_lastval) - [`bdr.trigger_get_committs`](/pgd/latest/reference/streamtriggers/rowfunctions#bdrtrigger_get_committs) - [`bdr.trigger_get_conflict_type`](/pgd/latest/reference/streamtriggers/rowfunctions#bdrtrigger_get_conflict_type) - [`bdr.trigger_get_origin_node_id`](/pgd/latest/reference/streamtriggers/rowfunctions#bdrtrigger_get_origin_node_id) - [`bdr.trigger_get_row`](/pgd/latest/reference/streamtriggers/rowfunctions#bdrtrigger_get_row) - [`bdr.trigger_get_type`](/pgd/latest/reference/streamtriggers/rowfunctions#bdrtrigger_get_type) - [`bdr.trigger_get_xid`](/pgd/latest/reference/streamtriggers/rowfunctions#bdrtrigger_get_xid) -- `bdr.wait_for_camo_partner_queue` +- [`bdr.wait_for_camo_partner_queue`](/pgd/latest/reference/functions#bdrwait_for_camo_partner_queue) - [`bdr.wait_slot_confirm_lsn`](/pgd/latest/reference/functions#bdrwait_slot_confirm_lsn) Many of these functions require additional privileges before you can use them. diff --git a/product_docs/docs/pgd/5/striggers.mdx b/product_docs/docs/pgd/5/striggers.mdx index 6e8fddd89fc..b691654d3f9 100644 --- a/product_docs/docs/pgd/5/striggers.mdx +++ b/product_docs/docs/pgd/5/striggers.mdx @@ -13,11 +13,11 @@ data processing on the downstream/target node: Together, these types of triggers are known as *stream triggers*. -!!! Note Permissions Required -Stream triggers are a PGD feature which requires permission. Any user wishing to use triggers, -the user must have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) -role assigned to them. -!!! +!!! Note Permissions Required +Stream triggers are a PGD feature which requires +permission. Any user wishing to create or drop triggers must have at least the +[bdr_application](security/pgd-predefined-roles/#bdr_application) role assigned +to them. !!! Stream triggers are designed to be trigger-like in syntax. They leverage the PostgreSQL BEFORE trigger architecture and are likely to have similar From 86efc2197c0255098d3d162ef90dbee68f7763b4 Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan <126472455+djw-m@users.noreply.github.com> Date: Mon, 8 Apr 2024 14:23:45 +0100 Subject: [PATCH 4/6] Update product_docs/docs/pgd/5/consistency/crdt.mdx Co-authored-by: Nick Babadzhanian <33933459+pgnickb@users.noreply.github.com> --- product_docs/docs/pgd/5/consistency/crdt.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pgd/5/consistency/crdt.mdx b/product_docs/docs/pgd/5/consistency/crdt.mdx index 26c228388d1..fb155df4f00 100644 --- a/product_docs/docs/pgd/5/consistency/crdt.mdx +++ b/product_docs/docs/pgd/5/consistency/crdt.mdx @@ -8,7 +8,7 @@ redirects: Conflict-free replicated data types (CRDT) support merging values from concurrently modified rows instead of discarding one of the rows as traditional resolution does. !!! Note Permissions Required -PGD CRDT require execute access to CRDT types, therefore a user must have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) role assigned to them. +PGD CRDT require usage access to CRDT types, therefore a user must have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) role assigned to them. !!! Each CRDT type is implemented as a separate PostgreSQL data type with an extra callback added to the `bdr.crdt_handlers` catalog. The merge process happens inside the PGD writer on the apply side without any user From f24439dd2616b087a18c079f34bc633c85d29ffc Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan <126472455+djw-m@users.noreply.github.com> Date: Mon, 8 Apr 2024 14:23:57 +0100 Subject: [PATCH 5/6] Update product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx Co-authored-by: Nick Babadzhanian <33933459+pgnickb@users.noreply.github.com> --- product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx b/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx index 2a472d9ad3d..ae00c9dd584 100644 --- a/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx +++ b/product_docs/docs/pgd/5/consistency/column-level-conflicts.mdx @@ -36,7 +36,7 @@ Column-level conflict resolution requires the table to have `REPLICA IDENTITY FU ## Enabling and disabling column-level conflict resolution !!! Note Permissions Required -Column level conflict detection uses the `column_timestamp` type. This requires the user to have have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) role assigned to them. +Column level conflict detection uses the `column_timestamps` type. This requires the user to have have at least the [bdr_application](security/pgd-predefined-roles/#bdr_application) role assigned to them. !!! The [bdr.alter_table_conflict_detection()](conflicts#bdralter_table_conflict_detection) function manages column-level conflict resolution. From 69a756f2d81e3efc81a816fb07df6d28d62f6c1e Mon Sep 17 00:00:00 2001 From: Dj Walker-Morgan <126472455+djw-m@users.noreply.github.com> Date: Wed, 17 Apr 2024 09:47:00 +0100 Subject: [PATCH 6/6] Improve text on internal sequence operators --- product_docs/docs/pgd/5/reference/functions-internal.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/product_docs/docs/pgd/5/reference/functions-internal.mdx b/product_docs/docs/pgd/5/reference/functions-internal.mdx index 0f6c8f222f5..19cb1d9acd3 100644 --- a/product_docs/docs/pgd/5/reference/functions-internal.mdx +++ b/product_docs/docs/pgd/5/reference/functions-internal.mdx @@ -371,19 +371,19 @@ the owner of the table, provided the owner has bdr_superuser privileges. Part of the internal implementation of global sequence manipulation. -Invoked automatically as needed. +Invoked automatically when `currval()` is called on a galloc or snowflakeid sequence. ### `bdr.seq_lastval` Part of the internal implementation of global sequence manipulation. -Invoked automatically as needed. +Invoked automatically when `lastval()` is called on a galloc or snowflakeid sequence. ### `bdr.seq_nextval` Part of the internal implementation of global sequence increments. -Invoked automatically as needed. +Invoked automatically when `nextval()` is called on a galloc or snowflakeid sequence ### `bdr.show_subscription_status`