Commit scopes ============= Commit scopes are rules that determine how transaction commits and conflicts are handled within a PGD system. You can read more about them in :ref:`Durability options (Group Commit/CAMO) ` . You can manipulate commit scopes using the following functions: - :ref:`bdr.add_commit_scope ` - :ref:`bdr.alter_commit_scope ` - :ref:`bdr.remove_commit_scope ` Commit scope syntax ------------------- The overall grammar for commit scope rules is composed as follows: :: commit_scope: commit_scope_operation [AND ...] commit_scope_operation: commit_scope_group confirmation_level commit_scope_kind commit_scope_group: { ANY num [NOT] (node_group [, ...]) | MAJORITY [NOT] (node_group [, ...]) | ALL [NOT] (node_group [, ...]) } confirmation_level: [ ON { received|replicated|durable|visible } ] commit_scope_kind: { GROUP COMMIT [ ( group_commit_parameter = value [, ...] ) ] [ ABORT ON ( abort_on_parameter = value ) ] | CAMO [ DEGRADE ON ( degrade_on_parameter = value ) TO ASYNC ] | LAG CONTROL [ ( lag_control_parameter = value [, ... ] ) ] | SYNCHRONOUS_COMMIT } Where ``node_group`` is the name of a PGD data node group. Commit scope groups ------------------- ANY ^^^ Example: ``ANY 2 (left_dc)`` A transaction under this commit scope group will be considered committed after any two nodes in the ``left_dc`` group confirm they processed the transaction. ANY NOT ^^^^^^^ Example: ``ANY 2 NOT (left_dc)`` A transaction under this commit scope group will be considered committed if any two nodes that aren’t in the ``left_dc`` group confirm they processed the transaction. MAJORITY ^^^^^^^^ Example: ``MAJORITY (left_dc)`` A transaction under this commit scope group will be considered committed if a majority of the nodes in the ``left_dc`` group confirm they processed the transaction. MAJORITY NOT ^^^^^^^^^^^^ Example: ``MAJORITY NOT (left_dc)`` A transaction under this commit scope group will be considered committed if a majority of the nodes that aren’t in the ``left_dc`` group confirm they processed the transaction. ALL ^^^ Example: ``ALL (left_dc)`` A transaction under this commit scope group will be considered committed if all of the nodes in the ``left_dc`` group confirm they processed the transaction. When ``ALL`` is used with :ref:`Group commit ` , the :ref:`commit_decision settings ` setting must be set to ``raft`` to avoid reconciliation issues. ALL NOT ^^^^^^^ Example: ``ALL NOT (left_dc)`` A transaction under this commit scope group will be considered committed if all of the nodes that aren’t in the ``left_dc`` group confirm they processed the transaction. Confirmation level ------------------ The confirmation level sets the point in time when a remote PGD node confirms that it reached a particular point in processing a transaction. ON received ^^^^^^^^^^^ A transaction is confirmed immediately after receiving it, prior to starting the local application. ON replicated ^^^^^^^^^^^^^ A transaction is confirmed after applying changes of the transaction but before flushing them to disk. ON durable ^^^^^^^^^^ A transaction is confirmed after all of its changes are flushed to disk. ON visible ^^^^^^^^^^ This is the default visibility. A transaction is confirmed after all of its changes are flushed to disk and it’s visible to concurrent transactions. Commit Scope kinds ------------------ More details of the commit scope kinds and details of their parameters: - :ref:`Group commit ` - :ref:`CAMO (Commit At Most Once) ` - :ref:`Lag Control ` - :ref:`PGD Synchronous Commit ` .. Note Parameter values :: Specify Boolean, enum, int, and interval values using the :ref:`Postgres GUC parameter value conventions ` . !!! GROUP COMMIT ------------ Allows commits to be confirmed by a consensus of nodes and controls conflict resolution settings. :: GROUP COMMIT [ ( group_commit_parameter = value [, ...] ) ] [ ABORT ON ( abort_on_parameter = value ) ] GROUP COMMIT parameters ^^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `transaction_tracking`,Boolean,Off/False,Specifies whether to track status of transaction. See :ref:`transaction_tracking settings` . `conflict_resolution`,enum,async,Specifies how to handle conflicts. (`async`I`eager` ). See :ref:`conflict_resolution settings` . `commit_decision`,enum,group,Specifies how the COMMIT decision is made. (`group`I`partner`I`raft`). See :ref:`commit_decision settings` . ABORT ON parameters ^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `timeout`,interval,0,Timeout in milliseconds (accepts other units). (0 means not set.) `require_write_lead`,bool,false,"CAMO only. If set, then for a transaction to switch to local (async) mode, a consensus request is required." transaction_tracking settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When set to true, two-phase commit transactions: - Look up commit decisions when a writer is processing a PREPARE message. - When recovering from an interruption, look up the transactions prepared before the interruption. When found, it then looks up the commit scope of the transaction and any corresponding RAFT commit decision. Suppose the node is the origin of the transaction and doesn’t have a RAFT commit decision, and ``transaction_tracking`` is on in the commit scope. In that case, it periodically looks for a RAFT commit decision for this unresolved transaction until it’s committed or aborted. conflict_resolution settings ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The value ``async`` means resolve conflicts asynchronously during replication using the conflict resolution policy. The value ``eager`` means that conflicts are resolved eagerly during COMMIT by aborting one of the conflicting transactions. Eager is only available with ``MAJORITY`` or ``ALL`` commit scope groups. When used with the ``ALL`` commit scope group, the :ref:`commit_decision settings ` must be set to ``raft`` to avoid reconcilation issue. See :ref:`Enabling and disabling column-level conflict resolution ` . commit_decision settings ^^^^^^^^^^^^^^^^^^^^^^^^ The value ``group`` means the preceding ``commit_scope_group`` specification also affects the COMMIT decision, not just durability. The value ``partner`` means the partner node decides whether transactions can be committed. This value is allowed only on groups with 2 data nodes. The value ``raft`` means the decision makes use of PGD’s built-in Raft consensus. Once all the nodes in the selected commit scope group have confirmed the transaction, to ensure that all the nodes in the PGD cluster have noted the transaction, it is noted with the all-node Raft. This option must be used when the ``ALL`` commit scope group is being used to ensure no divergence between the nodes over the decision. This option may have low performance. See :ref:`Commit decisions ` . CAMO ---- With the client’s cooperation, enables protection to prevent multiple insertions of the same transaction in failover scenarios. See :ref:`CAMO or commit-at-most-once ` for more details. :: CAMO [ DEGRADE ON ( degrade_on_parameter = value ) TO ASYNC ] Degrade On parameters ^^^^^^^^^^^^^^^^^^^^^ Allows degrading to asynchronous operation on timeout. .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable timeout,interval,0,Timeout in milliseconds (accepts other units) after which operation becomes asynchronous. (0 means not set.) require_write_lead,Boolean,False,Specifies whether the node must be a write lead to be able to switch to asynchronous mode. LAG CONTROL ----------- Allows the configuration of dynamic rate-limiting controlled by replication lag. See :ref:`Lag Control ` for more details. :: LAG CONTROL [ ( lag_control_parameter = value [, ... ] ) ] LAG CONTROL parameters ^^^^^^^^^^^^^^^^^^^^^^ .. csv-table:: :header: Parameter,Type,Default,Description :widths: 15,12,12,20 :align: left :class: longtable `max_lag_size`,int,0,"The maximum lag in kB that a given node can have in the replication connection to another node. When the lag exceeds this maximum scaled by `max_commit_delay`, lag control adjusts the commit delay." `max_lag_time`,interval,0,The maximum replication lag in milliseconds that the given origin can have with regard to a replication connection to a given downstream node. `max_commit_delay`,interval,0,"Configures the maximum delay each commit can take, in fractional milliseconds. If set to 0, it disables Lag Control. After each commit delay adjustment (for example, if the replication is lagging more than `max_lag_size` or `max_lag_time`), the commit delay is recalculated with the weight of the `bdr.lag_control_commit_delay_adjust` GUC. The `max_commit_delay` is a ceiling for the commit delay." - If ``max_lag_size`` and ``max_lag_time`` are set to 0, the LAG CONTROL is disabled. - If ``max_commit_delay`` is not set or set to 0, the LAG CONTROL is disabled. The lag size is derived from the delta of the ``send_ptr`` of the walsender to the ``apply_ptr`` of the receiver. The lag time is calculated according to the following formula: :: lag_time = (lag_size / apply_rate) * 1000; Where ``lag_size`` is the delta between the ``send_ptr`` and ``apply_ptr`` (as used for ``max_lag_size`` ), and ``apply_rate`` is a weighted exponential moving average, following the simplified formula: :: apply_rate = prev_apply_rate * (1 - apply_rate_weight) + ((apply_ptr_diff * apply_rate_weight) / diff_secs); Where: + ``prev_apply_rate`` was the previously configured ``apply_rate`` , before recalculating the new rate. + ``apply_rate_weight`` is the value of the GUC ``bdr.lag_tracker_apply_rate_weight`` . + ``apply_ptr_diff`` is the difference between the current ``apply_ptr`` and the ``apply_ptr`` at the point in time when the apply rate was last computed. + ``diff_secs`` is the delta in seconds from the last time the apply rate was calculated. SYNCHRONOUS_COMMIT ------------------ :: SYNCHRONOUS_COMMIT The ``SYNCHRONOUS_COMMIT`` commit scope kind has no parameters. It’s effectively configured only by the commit scope group and commit scope visibility.