Predefined commit scopes
========================

EDB Postgres Distributed (PGD) provides the following predefined commit
scopes available for use:

- :ref:`local protect <local protect>` 

- :ref:`lag protect <lag protect>` 

- :ref:`majority protect <majority protect>` 

- :ref:`adaptive protect <adaptive protect>` 

local protect
-------------

.. code:: text

   ASYNCHRONOUS COMMIT

The ``local protect`` commit scope is the default commit scope. It
provides asynchronous commit with no durability guarantees. This means
that transactions are considered committed as soon as they are written
to the local node’s WAL, without waiting for any confirmation from other
nodes in the cluster.

This commit scope is suitable for scenarios where high availability and
low latency are more important than data durability. However, it does
not provide any guarantees against data loss in case of node failures or
network issues.

lag protect
-----------

.. code:: text

   MAJORITY ORIGIN GROUP LAG CONTROL (max_lag_time = 30s, max_commit_delay = 10s)

The ``lag protect`` commit scope provides a durability guarantee based
on the lag time of the majority origin group. It ensures that
transactions are considered committed only when the lag time is within a
specified limit (30 seconds in this case) and the commit delay is also
within a specified limit (10 seconds in this case). This helps to
prevent data loss in case of network issues or node failures.

This commit scope is useful in scenarios where data consistency and
durability are important, but some latency is acceptable. It allows for
a balance between performance and data safety by ensuring that
transactions are not considered committed until they have been confirmed
by the majority of nodes in the origin group within the specified lag
and commit delay limits.

majority protect
----------------

.. code:: text

   MAJORITY ORIGIN GROUP SYNCHRONOUS COMMIT

The ``majority protect`` commit scope provides a durability guarantee
based on the majority origin group. It ensures that transactions are
considered committed only when they are confirmed by the majority of
nodes in the origin group. This helps to ensure data consistency and
durability in case of node failures or network issues.

This commit scope is suitable for scenarios where data consistency and
durability are critical, and it provides a higher level of protection
against data loss compared to the ``local protect`` commit scope.
However, it may introduce some latency due to the need for confirmation
from multiple nodes before considering a transaction as committed.

adaptive protect
----------------

.. code:: text

   MAJORITY ORIGIN GROUP SYNCHRONOUS COMMIT DEGRADE ON (timeout = 10s, require_write_lead = true) TO ASYNCHRONOUS COMMIT

The ``adaptive protect`` commit scope provides a more flexible
durability guarantee. It allows transactions to be considered committed
based on the majority origin group synchronous commit, but it can
degrade to asynchronous commit if the transaction cannot be confirmed
within a specified timeout (10 seconds in this case). This is useful in
scenarios where network latency or node failures may cause delays in
confirming transactions.

This commit scope is suitable for scenarios where data consistency and
durability are important, but some flexibility is needed to handle
potential delays. It provides a balance between performance and data
safety by allowing transactions to be considered committed even if they
cannot be confirmed by the majority of nodes within the specified
timeout, while still providing a higher level of protection compared to
the ``local protect`` commit scope.

Examples
--------

- Set the ``lag protect`` commit scope for a transaction using the
  ``SET LOCAL`` command:

.. code:: sql

     BEGIN;
     SET LOCAL bdr.commit_scope = lag protect;
     -- Your transaction statements here
     COMMIT;

This ensures that the transaction is committed with the specified commit
scope, providing the desired level of durability and availability.

- Set the ``majority protect`` commit scope for the entire session using
  the ``SET`` command:

.. code:: sql

     SET bdr.commit_scope = majority protect;

This ensures that all transactions executed in the session will use the
specified commit scope, providing the desired level of durability and
availability.

- Set the ``adaptive protect`` commit scope for a PGD group using the
  ``bdr.alter_node_group_option()`` function:

.. code:: sql

     SELECT bdr.alter_node_group_option(
             node_group_name:=mygroup,
             config_key:=default_commit_scope,
             config_value:=adaptive protect);

This ensures that all transactions executed in the specified PGD group
will use the specified commit scope, providing the desired level of
durability and availability, unless overridden by a session or
transaction-level setting.