This page documents the preview version (v2.21). Preview includes features under active development and is for development and testing only. For production, use the stable version (v2024.1). To learn more, see Versioning.
By default, YugabyteDB provides synchronous replication and strong consistency across geo-distributed data centers. However, many use cases do not require synchronous replication or justify the additional complexity and operational costs associated with managing three or more data centers. A cross-cluster (xCluster) deployment provides asynchronous replication across two data centers or cloud regions.
This document simulates a geo-distributed two-data-center (2DC) deployment using two local YugabyteDB clusters, one representing "Data Center - East" and the other representing "Data Center - West". Examples are based on the default database yugabyte
and the default user yugabyte
.
For more information, see the following:
- xCluster replication architecture
- xCluster replication commands
- Change data capture (CDC)
- yugabyted
- yb-admin
Create two data centers
Create and start your local clusters that simulate "Data Center - East" and "Data Center - West" by following instructions provided in Create two data centers.
Create keyspace and tables
Create the keyspace customers
and table users
on the "Data Center - East" cluster:
-
Open
ycqlsh
by specifying the host IP address of127.0.0.1
, as follows:./bin/ycqlsh 127.0.0.1
-
Create the
customers
keyspace by executing the following:CREATE KEYSPACE customers;
-
Enter the keyspace by executing the following:
USE customers;
-
Create the
users
table by executing the following:CREATE TABLE users ( email varchar PRIMARY KEY, username varchar );
Create the identical database table on the second cluster:
-
Open
ycqlsh
for "Data Center - West" by specifying the host IP address of127.0.0.2
, as follows:./bin/ycqlsh 127.0.0.2
-
Create the
customers
keyspace by executing the following:CREATE KEYSPACE customers;
-
Enter the keyspace by executing the following:
USE customers;
-
Create the
users
table by executing the following:CREATE TABLE users ( email varchar PRIMARY KEY, username varchar );
Having two identical tables on your clusters allows you to set up xCluster replication across two data centers.
Configure unidirectional replication
To configure "Data Center - West" to be the target of data changes from the "Data Center - East" cluster, follow instructions provided in Configure unidirectional replication.
Verify unidirectional replication
To check replication, you can add data to the users
table on one cluster and see that data appear in the users
table on your second cluster.
-
Use the following commands to add data to the "Data Center - East" cluster, making sure you are pointing to the new source host:
./bin/ycqlsh 127.0.0.1
ycqlsh:customers> INSERT INTO users(email, username) VALUES ('hector@example.com', 'hector'); ycqlsh:customers> INSERT INTO users(email, username) VALUES ('steve@example.com', 'steve');
-
On the target "Data Center - West" cluster, run the following commands to see that data has been replicated between clusters:
./bin/ycqlsh 127.0.0.2
ycqlsh:customers> SELECT * FROM users;
Expect the following output:
email | username ---------------------+---------- hector@example.com | hector steve@example.com | steve (2 rows)
Configure bidirectional replication
Bidirectional xCluster replication lets you insert data into the same table on either of the clusters and have the data changes added to the other cluster.
To configure bidirectional replication for the same table, follow instructions provided in Configure bidirectional replication.
Verify bidirectional replication
When the bidirectional replication has been configured, you can add data to the users
table on the "Data Center - West" cluster and see the data appear in the users
table on "Data Center - East" cluster.
-
Use the following commands to add data to the "Data Center - West" cluster, making sure you are pointing to the new source host:
./bin/ycqlsh 127.0.0.2
ycqlsh:customers> INSERT INTO users(email, username) VALUES ('neha@example.com', 'neha'); ycqlsh:customers> INSERT INTO users(email, username) VALUES ('mikhail@example.com', 'mikhail');
-
On the new target cluster, run the following commands to see that data has been replicated between clusters:
./bin/ycqlsh 127.0.0.1
ycqlsh:customers> SELECT * FROM users;
You should see the following output:
email | username ---------------------+---------- hector@example.com | hector steve@example.com | steve neha@example.com | neha mikhail@example.com | mikhail (4 rows)
Add tables
You can add more tables to an existing replication by following instructions provided in Add tables.
Clean up
You can shut down the local cluster by following the instructions provided in Destroy a local cluster.