Set up transactional xCluster (Automatic)

{{< note title="Note" >}} To use automatic-mode transactional xCluster replication, both the Primary and Standby universes must be running v2025.2.1 or later. {{< /note >}}

Automatic transactional xCluster replication handles all aspects of replication for both data and schema changes.

In particular, DDL changes made to the Primary universe are automatically replicated to the Standby universe.

{{< warning title="Warning" >}}

Not all DDLs can be automatically replicated yet; see XCluster Limitations.

{{< /warning >}}

In this mode, xCluster replication operates at the YSQL database granularity. This means you only run xCluster management operations when adding and removing databases from replication, and not when tables in the databases are created or dropped.

Set up Automatic mode replication

{{% readfile "includes/automatic-setup.md" %}}

Monitor replication

For information on monitoring xCluster replication, refer to Monitor xCluster.

Add a database to a replication group

{{% readfile "includes/transactional-add-db.md" %}}

Remove a database from a replication group

{{% readfile "includes/transactional-remove-db.md" %}}

{{< warning title="Warning" >}}

If you want the databases being removed from replication on the target to be usable after dropping replication, you need to stop your workload (including performing DDLs) to them and wait for the replication lag to reach zero before dropping the replication group.

If you take no precautions then the target databases may be unusable; we strongly recommend dropping such databases rather than attempting to use them.

{{< /warning >}}

Drop xCluster replication group

{{% readfile "includes/transactional-drop.md" %}}

{{< warning title="Be careful using this outside of the switchover or failover workflows" >}}

If you want the databases being replicated to on the target to be usable after dropping replication, you need to stop your workload (including performing DDLs) and wait for the replication lag to reach zero before dropping the replication group.

Alternatively, you can follow the failover workflow to ensure the target cuts over to a consistent time.

If you take no precautions then the target databases may be unusable; we strongly recommend dropping such databases rather than attempting to use them.

{{< /warning >}}

Making DDL changes

{{< warning title="Warning" >}}

Most DDLs can be automatically replicated, however there are still some Limitations.

{{< /warning >}}

DDL operations must only be performed on the Primary universe. All schema changes are automatically replicated to the Standby universe.

Check which universe is primary

To determine which universe is the Primary in xCluster replication, connect to a database that is in replication and run the following command:

SELECT yb_xcluster_ddl_replication.get_replication_role();

 get_replication_role
----------------------
 source
(1 row)

The source role indicates that you are talking to the Primary version of the database and that it is ready to accept traffic.

Other role values are possible depending on whether a setup or switchover is in progress and whether you are talking to the Primary or Standby. These other roles are subject to change in future releases.