Skip to content

Commit

Permalink
First set of edits on PGD doc re-read
Browse files Browse the repository at this point in the history
  • Loading branch information
ebgitelman committed Jun 13, 2024
1 parent e96dea1 commit c688b86
Show file tree
Hide file tree
Showing 4 changed files with 18 additions and 22 deletions.
2 changes: 1 addition & 1 deletion product_docs/docs/pgd/5/appusage/behavior.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ partitions are replicated downstream.
By default, triggers execute only on the origin node. For example, an INSERT
trigger executes on the origin node and is ignored when you apply the change on
the target node. You can specify for triggers to execute on both the origin node
at execution time and on the target when it's replicated ("apply time") by using
at execution time and on the target when it's replicated (*apply time*) by using
`ALTER TABLE ... ENABLE ALWAYS TRIGGER`. Or, use the `REPLICA` option to execute
only at apply time: `ALTER TABLE ... ENABLE REPLICA TRIGGER`.

Expand Down
2 changes: 1 addition & 1 deletion product_docs/docs/pgd/5/appusage/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -34,4 +34,4 @@ Developing an application with PGD is mostly the same as working with any Postgr

* [Table access methods](table-access-methods) (TAMs) notes the TAMs available with PGD and how to enable them.

* [Feature compatibility](feature-compatibility) shows which server features work with which commit scopes and which commit scopes can be daisychained together.
* [Feature compatibility](feature-compatibility) shows which server features work with which commit scopes and which commit scopes can be daisy chained together.
4 changes: 1 addition & 3 deletions product_docs/docs/pgd/5/cli/discover_connections.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ As with TPA, EDB PGD for Kubernetes is very flexible, and there are multiple way

Consult your configuration file to determine this information.

Establish a host name or IP address, port, database name, and username. The default database name is `bdrdb`, and the default username is enterprisedb for EDB Postgres Advanced Server and postgres for PostgreSQL and EDB Postgres Extended Server.
Establish a host name or IP address, port, database name, and username. The default database name is `bdrdb`. The default username is enterprisedb for EDB Postgres Advanced Server and postgres for PostgreSQL and EDB Postgres Extended Server.

You can then assemble a connection string based on that information:

Expand All @@ -93,5 +93,3 @@ You can then assemble a connection string based on that information:
```

If the deployment's configuration requires it, add `sslmode=<sslmode>`.


32 changes: 15 additions & 17 deletions product_docs/docs/pgd/5/ddl/ddl-locking.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,13 @@ title: DDL locking details
navTitle: Locking
---

Two kinds of locks enforce correctness of replicated DDL with PGD; the global DDL lock and the global DML lock.
Two kinds of locks enforce correctness of replicated DDL with PGD: the global DDL lock and the global DML lock.

### The global DDL lock

The first kind is known as a global DDL lock and is used only when `ddl_locking = 'all'`.
A global DDL lock prevents any other DDL from executing on the cluster while
each DDL statement runs. This ensures full correctness in the general case but
A global DDL lock is used only when `ddl_locking = 'all'`.
This kind of lock prevents any other DDL from executing on the cluster while
each DDL statement runs. This behavior ensures full correctness in the general case but
is too strict for many simple cases. PGD acquires a global lock on
DDL operations the first time in a transaction where schema changes are made.
This effectively serializes the DDL-executing transactions in the cluster. In
Expand All @@ -24,7 +24,7 @@ The lock request is sent by the regular replication stream, and the
nodes respond by the replication stream as well. So it's important that nodes (or
at least a majority of the nodes) run without much replication
delay. Otherwise it might take a long time for the node to acquire the DDL
lock. Once the majority of nodes agrees, the DDL execution is carried out.
lock. Once the majority of nodes agree, the DDL execution is carried out.

The ordering of DDL locking is decided using the Raft protocol. DDL statements
executed on one node are executed in the same sequence on all other nodes.
Expand All @@ -37,17 +37,17 @@ take a long time to acquire the lock. Hence it's preferable to run DDLs from a
single node or the nodes that have nearly caught up with replication changes
originating at other nodes.

A global DDL Lock has to be granted by a majority of data and witness nodes, where a majority is N/2+1
A global DDL lock must be granted by a majority of data and witness nodes, where a majority is N/2+1
of the eligible nodes. Subscriber-only nodes aren't eligible to participate.

### The global DML lock

The second kind is known as a global DML lock or relation DML lock. This kind of lock is used when
Known as a global DML lock or relation DML lock, this kind of lock is used when
either `ddl_locking = all` or `ddl_locking = dml`, and the DDL statement might cause
in-flight DML statements to fail. These failures can occur when you add or modify a constraint,
such as a unique constraint, check constraint, or NOT NULL constraint.
Relation DML locks affect only one relation at a time. Relation DML
locks ensure that no DDL executes while there are changes in the queue that
Relation DML locks affect only one relation at a time. These
locks ensure that no DDL executes while changes are in the queue that
might cause replication to halt with an error.

To acquire the global DML lock on a table, the PGD node executing the DDL
Expand All @@ -63,19 +63,17 @@ normally doesn't take an EXCLUSIVE LOCK or higher.

Waiting for pending DML operations to drain can take a long time and even longer
if replication is currently lagging.
This means that schema changes affecting row representation and constraints,
unlike with data changes, can be performed only while all configured nodes
This means that, unlike with data changes, schema changes affecting row representation and constraints can be performed only while all configured nodes
can be reached and are keeping up reasonably well with the current write rate.
If such DDL commands must be performed while a node is down, first remove the
down node from the configuration.


**All** eligible data notes must agree to grant a global DML lock before the lock is granted.
All eligible data notes must agree to grant a global DML lock before the lock is granted.
Witness and subscriber-only nodes aren't eligible to participate.

If a DDL statement isn't replicated, no global locks are acquired.

Locking behavior is specified by the [`bdr.ddl_locking`](/pgd/latest/reference/pgd-settings#bdrddl_locking) parameter, as
Specify locking behavior with the [`bdr.ddl_locking`](/pgd/latest/reference/pgd-settings#bdrddl_locking) parameter, as
explained in [Executing DDL on PGD systems](ddl-overview#executing-ddl-on-pgd-systems):

- `ddl_locking = all` takes global DDL lock and, if needed, takes relation DML lock.
Expand All @@ -85,20 +83,20 @@ explained in [Executing DDL on PGD systems](ddl-overview#executing-ddl-on-pgd-sy
Some PGD functions make DDL changes. For those functions,
DDL locking behavior applies, which is noted in the documentation for each function.

Thus, `ddl_locking = dml` is only safe when you can guarantee that
Thus, `ddl_locking = dml` is safe only when you can guarantee that
no conflicting DDL is executed from other nodes. With this setting,
the statements that require only the global DDL lock don't use the global
locking at all.

`ddl_locking = off` is only safe when you can guarantee that there are no
`ddl_locking = off` is safe only when you can guarantee that there are no
conflicting DDL and no conflicting DML operations on the database objects
DDL executes on. If you turn locking off and then experience difficulties,
you might lose in-flight changes to data. The user application team needs to resolve any issues caused.

In some cases, concurrently executing DDL can properly be serialized.
If these serialization failures occur, the DDL might reexecute.

DDL replication isn't active on logical standby nodes until they are promoted.
DDL replication isn't active on logical standby nodes until they're promoted.

Some PGD management functions act like DDL, meaning that they
attempt to take global locks, and their actions are replicated if DDL
Expand Down

0 comments on commit c688b86

Please sign in to comment.