Durability in PGD Essential
===========================

By default PGD Essential uses asynchronous replication between its
nodes, but it can be configured to use synchronous replication as well.
This allows for a high degree of flexibility in terms of data durability
and availability. Asynchronous replication offers lower latency and
higher throughput, while synchronous replication provides stronger
consistency guarantees at the cost of performance. PGD Essential allows
you to choose the replication strategy through the use of commit scopes.

Commit Scopes
-------------

Commit scopes are a powerful feature of PGD Essential that allow you to
control the durability and availability of your data. They enable you to
specify the level of durability required for each transaction, allowing
you to balance performance and consistency based on your application’s
needs. PGD Essential has four pre-defined commit scopes that you can use
to control the durability of your transactions, among other things.

- local protect

- lag protect

- majority protect

- adaptive protect

The predefined commit scopes in PGD Essential are designed to provide a
balance between performance and data safety. You cannot add, remove or
modify a PGD Essential commit scope. In PGD Expanded, you can create and
manage your own commit scopes, allowing for more flexibility and control
over the durability guarantees.

local protect
^^^^^^^^^^^^^

This is the default commit scope for PGD Essential. 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.

lag protect
^^^^^^^^^^^

This commit scope 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.

majority protect
^^^^^^^^^^^^^^^^

This 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.

adaptive protect
^^^^^^^^^^^^^^^^

This 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.

For more information on commit scopes, see the `Commit Scopes <https://www.enterprisedb.com/docs/pgd/latest/reference/commit-scopes/>`_  reference
section and the `Predefined Commit Scopes <https://www.enterprisedb.com/docs/pgd/latest/reference/commit-scopes/predefined-commit-scopes/>`_  reference page.

Using Commit Scopes
-------------------

To use commit scopes in PGD Essential, you can specify the desired
commit scope when executing a transaction. This allows you to control
the durability and availability of your data based on your application’s
needs. For example, you can use the ``lag protect`` commit scope for
transactions that require a higher level of durability, while using the
``local protect`` commit scope for transactions that prioritize
performance over durability.

Within a transaction
^^^^^^^^^^^^^^^^^^^^

You can specify the commit scope for a transaction using the
``SET LOCAL`` command. For example, to use the ``lag protect`` commit
scope for a transaction, you can execute the following commands:

.. code:: sql

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

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

For a session
^^^^^^^^^^^^^

You can also set the commit scope for the entire session using the
``SET`` command. For example, to set the ``majority protect`` commit
scope for the entire session, you can execute the following command:

.. code:: sql

   SET bdr.commit_scope = majority protect;

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

For a group
^^^^^^^^^^^

You can also set the default commit scope for a PGD group using the
``bdr.alter_node_group_option()`` function. For example, to set the
``adaptive protect`` commit scope for a PGD group, you can execute the
following command:

.. code:: sql

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

This will ensure 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.