From aec9a667dc2056a395292c62144d6f30e1ba847c Mon Sep 17 00:00:00 2001
From: Dwight Hodge <79169168+ddhodge@users.noreply.github.com>
Date: Wed, 11 Sep 2024 10:16:26 -0400
Subject: [PATCH] [doc][xcluster] Truncate limitation (#23833)
* DOC-460
* review comment
* stable
* stable
---
.../docdb-replication/async-replication.md | 6 +--
.../multi-dc/async-replication/_index.md | 37 +++++++------------
.../async-replication-transactional.md | 2 +-
.../disaster-recovery/_index.md | 4 +-
.../disaster-recovery-tables.md | 1 +
.../xcluster-replication/_index.md | 4 +-
.../xcluster-replication-ddl.md | 1 +
.../docdb-replication/async-replication.md | 6 +--
.../multi-dc/async-replication/_index.md | 37 +++++++------------
.../async-replication-transactional.md | 2 +-
.../disaster-recovery/_index.md | 4 +-
.../disaster-recovery-tables.md | 1 +
.../xcluster-replication/_index.md | 4 +-
.../xcluster-replication-ddl.md | 1 +
.../docdb-replication/async-replication.md | 2 +-
15 files changed, 49 insertions(+), 63 deletions(-)
diff --git a/docs/content/preview/architecture/docdb-replication/async-replication.md b/docs/content/preview/architecture/docdb-replication/async-replication.md
index 53322f2675d6..cb5714794ae4 100644
--- a/docs/content/preview/architecture/docdb-replication/async-replication.md
+++ b/docs/content/preview/architecture/docdb-replication/async-replication.md
@@ -167,7 +167,7 @@ xCluster currently supports active-active single-master and active-active multi-
### Active-active single-master
-Here the replication is unidirectional from a source universe to a target universe. The target universe is typically located in data centers or regions that are different from the source universe. The source universe can serve both reads and writes. The target universe can only serve reads. Since only the nodes in one universe can take writes this mode is referred to as single master. Note that within the source universe all nodes can serve writes.
+In this setup the replication is unidirectional from a source universe to a target universe. The target universe is typically located in data centers or regions that are different from the source universe. The source universe can serve both reads and writes. The target universe can only serve reads. Since only the nodes in one universe can take writes this mode is referred to as single master. Note that within the source universe all nodes can serve writes.
Usually, such deployments are used for serving low-latency reads from the target universes, as well as for disaster recovery purposes. When used primarily for disaster recovery purposes, these deployments are also called active-standby because the target universe stands by to take over if the source universe is lost.
@@ -243,7 +243,7 @@ After losing one universe, the other universe may be left with torn transactions
### Transactional-mode limitations
-With transactional mode,
+Transactional mode has the following limitations:
- No writes are allowed in the target universe
- Active-active multi-master is not supported
@@ -259,7 +259,7 @@ When the source universe is lost, an explicit decision must be made to switch ov
### DDL changes
- Currently, DDL changes are not automatically replicated. Applying commands such as `CREATE TABLE`, `ALTER TABLE`, and `CREATE INDEX` to the target universes is your responsibility.
-- `DROP TABLE` is not supported. You must first disable replication for this table.
+- `DROP TABLE` is not supported in YCQL. You must first disable replication for this table.
- `TRUNCATE TABLE` is not supported. This is an underlying limitation, due to the level at which the two features operate. That is, replication is implemented on top of the Raft WAL files, while truncate is implemented on top of the RocksDB SST files.
- In the future, it will be possible to propagate DDL changes safely to other universes. This is tracked in [#11537](https://github.com/yugabyte/yugabyte-db/issues/11537).
diff --git a/docs/content/preview/deploy/multi-dc/async-replication/_index.md b/docs/content/preview/deploy/multi-dc/async-replication/_index.md
index 055dc473ce7b..c6d6bcfcfe14 100644
--- a/docs/content/preview/deploy/multi-dc/async-replication/_index.md
+++ b/docs/content/preview/deploy/multi-dc/async-replication/_index.md
@@ -16,29 +16,18 @@ By default, YugabyteDB provides synchronous replication and strong consistency a
For information on xCluster deployment architecture, replication scenarios, and limitations, refer to [xCluster replication](../../../architecture/docdb-replication/async-replication/).
-
+ {{}}
+
+{{}}
diff --git a/docs/content/preview/deploy/multi-dc/async-replication/async-replication-transactional.md b/docs/content/preview/deploy/multi-dc/async-replication/async-replication-transactional.md
index 49d5eb1a0f1d..3126657a1455 100644
--- a/docs/content/preview/deploy/multi-dc/async-replication/async-replication-transactional.md
+++ b/docs/content/preview/deploy/multi-dc/async-replication/async-replication-transactional.md
@@ -35,8 +35,8 @@ xCluster safe time is the transactionally consistent time across all tables in a
Transactional xCluster can be set up in the following ways:
-- [Manual mode](../async-transactional-setup/).
- [Semi-automatic mode](../async-transactional-setup-dblevel/), providing operationally simpler setup and management of replication, as well as simpler steps for performing DDL changes.
+- [Manual mode](../async-transactional-setup/).
## Limitations
diff --git a/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md b/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md
index 033e5d4fcec3..cdbd39e8b335 100644
--- a/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md
+++ b/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md
@@ -64,7 +64,7 @@ Blog: [Using YugabyteDB xCluster DR for PostgreSQL Disaster Recovery in Azure](h
## Limitations
-- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YugabyteDB Anywhere. Refer to [Manage tables and indexes](./disaster-recovery-tables/).
+- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YugabyteDB Anywhere. In addition, xCluster does not support truncate operations. Refer to [Manage tables and indexes](./disaster-recovery-tables/).
- DR setup (and other operations that require making a full copy from DR primary to DR replica, such as adding tables with data to replication, resuming replication after an extended network outage, and so on) may fail with the error `database "" is being accessed by other users`.
@@ -74,6 +74,8 @@ Blog: [Using YugabyteDB xCluster DR for PostgreSQL Disaster Recovery in Azure](h
- Setting up DR between a universe upgraded to v2.20.x and a new v2.20.x universe is not supported. This is due to a limitation of xCluster deployments and packed rows. See [Packed row limitations](../../../architecture/docdb/packed-rows/#limitations).
+For more information on the YugabyteDB xCluster implementation and its limitations, refer to [xCluster implementation limitations](../../../architecture/docdb-replication/async-replication/#limitations).
+
## Upgrading universes in DR
When [upgrading universes](../../manage-deployments/upgrade-software-install/) in DR replication, you should upgrade and finalize the DR replica before upgrading and finalizing the DR primary.
diff --git a/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md b/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md
index 6ded687fa409..02493e64c6c8 100644
--- a/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md
+++ b/docs/content/preview/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md
@@ -34,6 +34,7 @@ In addition, keep in mind the following:
- If you are using Colocated tables, you CREATE TABLE on DR primary, then CREATE TABLE on DR replica making sure that you force the Colocation ID to be identical to that on DR primary.
- If you try to make a DDL change on DR primary and it fails, you must also make the same attempt on DR replica and get the same failure.
+- TRUNCATE TABLE is not supported. To truncate a table, pause replication, truncate the table on both primary and standby, and resume replication.
Use the following guidance when managing tables and indexes in universes with DR configured.
diff --git a/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/_index.md b/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/_index.md
index 4f62d82cc143..a9efc414e256 100644
--- a/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/_index.md
+++ b/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/_index.md
@@ -83,7 +83,7 @@ Video: [YFTT - Transactional xCluster](https://www.youtube.com/watch?lI6gw7ncBs8
## Limitations
-- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YugabyteDB Anywhere. Refer to [Manage tables and indexes](./xcluster-replication-ddl/).
+- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YugabyteDB Anywhere. In addition, xCluster does not support truncate operations. Refer to [Manage tables and indexes](./xcluster-replication-ddl/).
- xCluster Replication setup (and other operations that require making a [full copy](xcluster-replication-setup/#full-copy-during-xcluster-setup) from source to target) forcefully drop the tables on the target if they exist before performing the restore.
@@ -99,4 +99,4 @@ Video: [YFTT - Transactional xCluster](https://www.youtube.com/watch?lI6gw7ncBs8
- xCluster Replication is not supported for [materialized views](../../../explore/ysql-language-features/advanced-features/views/#materialized-views).
-For more information, refer to [xCluster implementation limitations](../../../architecture/docdb-replication/async-replication/#limitations).
+For more information on the YugabyteDB xCluster implementation and its limitations, refer to [xCluster implementation limitations](../../../architecture/docdb-replication/async-replication/#limitations).
diff --git a/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md b/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md
index 9251b67ca2da..6463c13777e3 100644
--- a/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md
+++ b/docs/content/preview/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md
@@ -71,6 +71,7 @@ In addition, keep in mind the following:
- If you are using Colocated tables, you CREATE TABLE on target, then CREATE TABLE on source, making sure that you force the Colocation ID to be identical to that on target.
- If you try to make a DDL change on source and it fails, you must also make the same attempt on target and get the same failure.
+- TRUNCATE TABLE is not supported. To truncate a table, pause replication, truncate the table on both source and target, and resume replication.
Use the following guidance when managing tables and indexes in universes with replication configured.
diff --git a/docs/content/stable/architecture/docdb-replication/async-replication.md b/docs/content/stable/architecture/docdb-replication/async-replication.md
index ee49096eedca..cc182b20c913 100644
--- a/docs/content/stable/architecture/docdb-replication/async-replication.md
+++ b/docs/content/stable/architecture/docdb-replication/async-replication.md
@@ -165,7 +165,7 @@ xCluster currently supports active-active single-master and active-active multi-
### Active-active single-master
-Here the replication is unidirectional from a source universe to a target universe. The target universe is typically located in data centers or regions that are different from the source universe. The source universe can serve both reads and writes. The target universe can only serve reads. Since only the nodes in one universe can take writes this mode is referred to as single master. Note that within the source universe all nodes can serve writes.
+In this setup the replication is unidirectional from a source universe to a target universe. The target universe is typically located in data centers or regions that are different from the source universe. The source universe can serve both reads and writes. The target universe can only serve reads. Since only the nodes in one universe can take writes this mode is referred to as single master. Note that within the source universe all nodes can serve writes.
Usually, such deployments are used for serving low-latency reads from the target universes, as well as for disaster recovery purposes. When used primarily for disaster recovery purposes, these deployments are also called active-standby because the target universe stands by to take over if the source universe is lost.
@@ -241,7 +241,7 @@ After losing one universe, the other universe may be left with torn transactions
### Transactional-mode limitations
-With transactional mode,
+Transactional mode has the following limitations:
- No writes are allowed in the target universe
- Active-active multi-master is not supported
@@ -257,7 +257,7 @@ When the source universe is lost, an explicit decision must be made to switch ov
### DDL changes
- Currently, DDL changes are not automatically replicated. Applying commands such as `CREATE TABLE`, `ALTER TABLE`, and `CREATE INDEX` to the target universes is your responsibility.
-- `DROP TABLE` is not supported. You must first disable replication for this table.
+- `DROP TABLE` is not supported in YCQL. You must first disable replication for this table.
- `TRUNCATE TABLE` is not supported. This is an underlying limitation, due to the level at which the two features operate. That is, replication is implemented on top of the Raft WAL files, while truncate is implemented on top of the RocksDB SST files.
- In the future, it will be possible to propagate DDL changes safely to other universes. This is tracked in [#11537](https://github.com/yugabyte/yugabyte-db/issues/11537).
diff --git a/docs/content/stable/deploy/multi-dc/async-replication/_index.md b/docs/content/stable/deploy/multi-dc/async-replication/_index.md
index 8ce138e073c7..cf9eb67611ef 100644
--- a/docs/content/stable/deploy/multi-dc/async-replication/_index.md
+++ b/docs/content/stable/deploy/multi-dc/async-replication/_index.md
@@ -16,29 +16,18 @@ By default, YugabyteDB provides synchronous replication and strong consistency a
For information on xCluster deployment architecture, replication scenarios, and limitations, refer to [xCluster replication](../../../architecture/docdb-replication/async-replication/).
-
+ {{}}
+
+{{}}
diff --git a/docs/content/stable/deploy/multi-dc/async-replication/async-replication-transactional.md b/docs/content/stable/deploy/multi-dc/async-replication/async-replication-transactional.md
index a2d41eaa8016..a40aa07481fc 100644
--- a/docs/content/stable/deploy/multi-dc/async-replication/async-replication-transactional.md
+++ b/docs/content/stable/deploy/multi-dc/async-replication/async-replication-transactional.md
@@ -33,8 +33,8 @@ xCluster safe time is the transactionally consistent time across all tables in a
Transactional xCluster can be set up in the following ways:
-- [Manual mode](../async-transactional-setup/).
- [Semi-automatic mode](../async-transactional-setup-dblevel/), providing operationally simpler setup and management of replication, as well as simpler steps for performing DDL changes.
+- [Manual mode](../async-transactional-setup/).
## Limitations
diff --git a/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md b/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md
index 08d5288a7f38..e4c54656243e 100644
--- a/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md
+++ b/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/_index.md
@@ -64,7 +64,7 @@ Blog: [Using YugabyteDB xCluster DR for PostgreSQL Disaster Recovery in Azure](h
## Limitations
-- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YBA. Refer to [Manage tables and indexes](./disaster-recovery-tables/).
+- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YugabyteDB Anywhere. In addition, xCluster does not support truncate operations. Refer to [Manage tables and indexes](./disaster-recovery-tables/).
- DR setup (and other operations that require making a full copy from DR primary to DR replica, such as adding tables with data to replication, resuming replication after an extended network outage, and so on) may fail with the error `database "" is being accessed by other users`.
@@ -74,6 +74,8 @@ Blog: [Using YugabyteDB xCluster DR for PostgreSQL Disaster Recovery in Azure](h
- Setting up DR between a universe upgraded to v2.20.x and a new v2.20.x universe is not supported. This is due to a limitation of xCluster deployments and packed rows. See [Packed row limitations](../../../architecture/docdb/packed-rows/#limitations).
+For more information on the YugabyteDB xCluster implementation and its limitations, refer to [xCluster implementation limitations](../../../architecture/docdb-replication/async-replication/#limitations).
+
## Upgrading universes in DR
When [upgrading universes](../../manage-deployments/upgrade-software-install/) in DR replication, you should upgrade and finalize the DR replica before upgrading and finalizing the DR primary.
diff --git a/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md b/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md
index ffff9e3bf7da..f3dfb3ad7c35 100644
--- a/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md
+++ b/docs/content/stable/yugabyte-platform/back-up-restore-universes/disaster-recovery/disaster-recovery-tables.md
@@ -34,6 +34,7 @@ In addition, keep in mind the following:
- If you are using Colocated tables, you CREATE TABLE on DR primary, then CREATE TABLE on DR replica making sure that you force the Colocation ID to be identical to that on DR primary.
- If you try to make a DDL change on DR primary and it fails, you must also make the same attempt on DR replica and get the same failure.
+- TRUNCATE TABLE is not supported. To truncate a table, pause replication, truncate the table on both primary and standby, and resume replication.
Use the following guidance when managing tables and indexes in universes with DR configured.
diff --git a/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/_index.md b/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/_index.md
index cd064e5eb3de..6153b901d392 100644
--- a/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/_index.md
+++ b/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/_index.md
@@ -83,7 +83,7 @@ Video: [YFTT - Transactional xCluster](https://www.youtube.com/watch?lI6gw7ncBs8
## Limitations
-- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YugabyteDB Anywhere. Refer to [Manage tables and indexes](./xcluster-replication-ddl/).
+- Currently, replication of DDL (SQL-level changes such as creating or dropping tables or indexes) is not supported. To make these changes requires first performing the DDL operation (for example, creating a table), and then adding the new object to replication in YugabyteDB Anywhere. In addition, xCluster does not support truncate operations. Refer to [Manage tables and indexes](./xcluster-replication-ddl/).
- xCluster Replication setup (and other operations that require making a [full copy](xcluster-replication-setup/#full-copy-during-xcluster-setup) from source to target) forcefully drop the tables on the target if they exist before performing the restore.
@@ -99,4 +99,4 @@ Video: [YFTT - Transactional xCluster](https://www.youtube.com/watch?lI6gw7ncBs8
- xCluster Replication is not supported for [materialized views](../../../explore/ysql-language-features/advanced-features/views/#materialized-views).
-For more information, refer to [xCluster implementation limitations](../../../architecture/docdb-replication/async-replication/#limitations).
+For more information on the YugabyteDB xCluster implementation and its limitations, refer to [xCluster implementation limitations](../../../architecture/docdb-replication/async-replication/#limitations).
diff --git a/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md b/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md
index 850fab418ad5..f5c7e7b13483 100644
--- a/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md
+++ b/docs/content/stable/yugabyte-platform/manage-deployments/xcluster-replication/xcluster-replication-ddl.md
@@ -71,6 +71,7 @@ In addition, keep in mind the following:
- If you are using Colocated tables, you CREATE TABLE on target, then CREATE TABLE on source, making sure that you force the Colocation ID to be identical to that on target.
- If you try to make a DDL change on source and it fails, you must also make the same attempt on target and get the same failure.
+- TRUNCATE TABLE is not supported. To truncate a table, pause replication, truncate the table on both source and target, and resume replication.
Use the following guidance when managing tables and indexes in universes with replication configured.
diff --git a/docs/content/v2.20/architecture/docdb-replication/async-replication.md b/docs/content/v2.20/architecture/docdb-replication/async-replication.md
index d5f17e08e8de..12435faca9de 100644
--- a/docs/content/v2.20/architecture/docdb-replication/async-replication.md
+++ b/docs/content/v2.20/architecture/docdb-replication/async-replication.md
@@ -257,7 +257,7 @@ When the source universe is lost, an explicit decision must be made to switch ov
### DDL changes
- Currently, DDL changes are not automatically replicated. Applying commands such as `CREATE TABLE`, `ALTER TABLE`, and `CREATE INDEX` to the target universes is your responsibility.
-- `DROP TABLE` is not supported. You must first disable replication for this table.
+- `DROP TABLE` is not supported in YCQL. You must first disable replication for this table.
- `TRUNCATE TABLE` is not supported. This is an underlying limitation, due to the level at which the two features operate. That is, replication is implemented on top of the Raft WAL files, while truncate is implemented on top of the RocksDB SST files.
- In the future, it will be possible to propagate DDL changes safely to other universes. This is tracked in [#11537](https://github.com/yugabyte/yugabyte-db/issues/11537).
-