diff --git a/product_docs/docs/pgd/4.4/bdr/appusage.mdx b/product_docs/docs/pgd/4.4/bdr/appusage.mdx index c17e6f754e..5339e2e2b8 100644 --- a/product_docs/docs/pgd/4.4/bdr/appusage.mdx +++ b/product_docs/docs/pgd/4.4/bdr/appusage.mdx @@ -107,9 +107,23 @@ with nonmatching collation qualifiers. Row filters might be affected by differences in collations if collatable expressions were used. BDR handling of very long "toasted" data in PostgreSQL is transparent to -the user. The TOAST "chunkid" values likely differ between +the user. The `TOAST` "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! + BDR can't work correctly if Replica Identity columns are marked as external. PostgreSQL allows CHECK() constraints that contain volatile functions. Since diff --git a/product_docs/docs/pgd/5.6/appusage/behavior.mdx b/product_docs/docs/pgd/5.6/appusage/behavior.mdx index 451df72c85..018359f7c7 100644 --- a/product_docs/docs/pgd/5.6/appusage/behavior.mdx +++ b/product_docs/docs/pgd/5.6/appusage/behavior.mdx @@ -129,6 +129,20 @@ PGD handling of very long "toasted" data in PostgreSQL is transparent to the user. The TOAST "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! + ### Other restrictions PGD can't work correctly if Replica Identity columns are marked as external. diff --git a/product_docs/docs/pgd/5.7/appusage/behavior.mdx b/product_docs/docs/pgd/5.7/appusage/behavior.mdx index 451df72c85..018359f7c7 100644 --- a/product_docs/docs/pgd/5.7/appusage/behavior.mdx +++ b/product_docs/docs/pgd/5.7/appusage/behavior.mdx @@ -129,6 +129,20 @@ PGD handling of very long "toasted" data in PostgreSQL is transparent to the user. The TOAST "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! + ### Other restrictions PGD can't work correctly if Replica Identity columns are marked as external. diff --git a/product_docs/docs/pgd/5.8/appusage/behavior.mdx b/product_docs/docs/pgd/5.8/appusage/behavior.mdx index 451df72c85..018359f7c7 100644 --- a/product_docs/docs/pgd/5.8/appusage/behavior.mdx +++ b/product_docs/docs/pgd/5.8/appusage/behavior.mdx @@ -129,6 +129,20 @@ PGD handling of very long "toasted" data in PostgreSQL is transparent to the user. The TOAST "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! + ### Other restrictions PGD can't work correctly if Replica Identity columns are marked as external. diff --git a/product_docs/docs/pgd/5.9/appusage/behavior.mdx b/product_docs/docs/pgd/5.9/appusage/behavior.mdx index 451df72c85..018359f7c7 100644 --- a/product_docs/docs/pgd/5.9/appusage/behavior.mdx +++ b/product_docs/docs/pgd/5.9/appusage/behavior.mdx @@ -129,6 +129,20 @@ PGD handling of very long "toasted" data in PostgreSQL is transparent to the user. The TOAST "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! + ### Other restrictions PGD can't work correctly if Replica Identity columns are marked as external. diff --git a/product_docs/docs/pgd/6.1/appusage/behavior.mdx b/product_docs/docs/pgd/6.1/appusage/behavior.mdx index 5bd29c9d03..39d3b0a210 100644 --- a/product_docs/docs/pgd/6.1/appusage/behavior.mdx +++ b/product_docs/docs/pgd/6.1/appusage/behavior.mdx @@ -132,6 +132,20 @@ PGD handling of very long "toasted" data in PostgreSQL is transparent to the user. The TOAST "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! + ### Other restrictions PGD can't work correctly if Replica Identity columns are marked as external. diff --git a/product_docs/docs/pgd/6.2/appusage/behavior.mdx b/product_docs/docs/pgd/6.2/appusage/behavior.mdx index 5bd29c9d03..39d3b0a210 100644 --- a/product_docs/docs/pgd/6.2/appusage/behavior.mdx +++ b/product_docs/docs/pgd/6.2/appusage/behavior.mdx @@ -132,6 +132,20 @@ PGD handling of very long "toasted" data in PostgreSQL is transparent to the user. The TOAST "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! + ### Other restrictions PGD can't work correctly if Replica Identity columns are marked as external. diff --git a/product_docs/docs/pgd/6.3/developing-applications/planning.mdx b/product_docs/docs/pgd/6.3/developing-applications/planning.mdx index bcf32d2ce6..be1db7a8bb 100644 --- a/product_docs/docs/pgd/6.3/developing-applications/planning.mdx +++ b/product_docs/docs/pgd/6.3/developing-applications/planning.mdx @@ -62,6 +62,8 @@ The following behaviors differ from a single-node database and require attention - Use `BYTEA` for binary data. `BYTEA` columns replicate fully, including the underlying `TOAST` storage, up to 1 GB. The [PostgreSQL large object](https://www.postgresql.org/docs/current/largeobjects.html) facility isn't supported in PGD. +- Use `REPLICA IDENTITY FULL` on tables with `TOAST`-able columns (`text`, `bytea`, `jsonb`, large `varchar`, and so on). PGD 6 sets this by default for new tables via the `BDR_AUTO` replica identity. Overriding it with `REPLICA IDENTITY DEFAULT` or `USING INDEX` risks data divergence under concurrent updates. Rows whose total `TOAST` data exceeds approximately 1 GB can't be replicated regardless of this setting. + - Avoid volatile functions in `CHECK` constraints. PGD reexecutes `CHECK` constraints on apply by default, and if a volatile function returns a different result than it did on the origin, replication can break. This behavior is controlled by the [`check_constraints`](/pgd/current/reference/cli/command_ref/group/set-option/) group option. - Don't mark `REPLICA IDENTITY` columns as external. diff --git a/product_docs/docs/pgd/6.4/developing-applications/planning.mdx b/product_docs/docs/pgd/6.4/developing-applications/planning.mdx index e9311e2c3b..c144e1c23b 100644 --- a/product_docs/docs/pgd/6.4/developing-applications/planning.mdx +++ b/product_docs/docs/pgd/6.4/developing-applications/planning.mdx @@ -62,6 +62,8 @@ The following behaviors differ from a single-node database and require attention - Use `BYTEA` columns for binary data. They replicate fully, including the underlying `TOAST` storage, up to 1 GB. If your application requires the stream-oriented large object interface, PGD also supports [replicated large objects](/pgd/current/large-objects/). +- Use `REPLICA IDENTITY FULL` on tables with `TOAST`-able columns (`text`, `bytea`, `jsonb`, large `varchar`, and so on). PGD 6 sets this by default for new tables via the `BDR_AUTO` replica identity. Overriding it with `REPLICA IDENTITY DEFAULT` or `USING INDEX` risks data divergence under concurrent updates. Rows whose total `TOAST` data exceeds approximately 1 GB can't be replicated regardless of this setting. + - Avoid volatile functions in `CHECK` constraints. PGD reexecutes `CHECK` constraints on apply by default, and if a volatile function returns a different result than it did on the origin, replication can break. This behavior is controlled by the [`check_constraints`](/pgd/current/reference/cli/command_ref/group/set-option/) group option. - Don't mark `REPLICA IDENTITY` columns as external. diff --git a/product_docs/docs/pgd/6/appusage/behavior.mdx b/product_docs/docs/pgd/6/appusage/behavior.mdx index 5bd29c9d03..1889548425 100644 --- a/product_docs/docs/pgd/6/appusage/behavior.mdx +++ b/product_docs/docs/pgd/6/appusage/behavior.mdx @@ -132,6 +132,19 @@ PGD handling of very long "toasted" data in PostgreSQL is transparent to the user. The TOAST "chunkid" values likely differ between the same row on different nodes, but that doesn't cause any problems. +!!! Warning REPLICA IDENTITY FULL required for tables with TOAST-able columns +Tables that hold `TOAST`-able column types (`text`, `bytea`, `jsonb`, large `varchar`, and so on) must use `REPLICA IDENTITY FULL`. BDR 4 doesn't set this behavior by default. Enable it explicitly on every table that can store `TOAST` values: + +```sql +ALTER TABLE your_table REPLICA IDENTITY FULL; +``` +!!! + +When an `UPDATE` doesn't change a `TOAST` column, the column is sent in the replication stream as an unchanged marker rather than as full data. Under `REPLICA IDENTITY FULL`, Postgres flattens the entire pre-update row (including its `TOAST` data) into WAL, so the receiver always has an authoritative source for unchanged columns. Under `REPLICA IDENTITY DEFAULT` (or `USING INDEX`), the receiver fills unchanged `TOAST` columns from its local copy of the row, which may be stale if a concurrent update on another node modified a different column of the same row, resulting in data divergence between nodes. + +!!! Note +`REPLICA IDENTITY FULL` doesn't enable replicating rows whose total `TOAST` data exceeds approximately 1 GB. Updates on such rows fail at the source with `invalid memory alloc request size` because Postgres must flatten the entire pre-update row in memory before WAL logging, and the flattened tuple exceeds `MaxAllocSize`. There's currently no replication-safe path for rows of that size. Avoid creating them. +!!! ### Other restrictions PGD can't work correctly if Replica Identity columns are marked as external.