YugabyteDB Docs

YSQL
YCQL

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:

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 of 127.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 of 127.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.