---
metadata:
  - name: generator
    content: Diplodoc Platform v5.52.0
alternate:
  - https://ydb.tech/docs/en/concepts/async-replication.md?version=v25.3
  - https://ydb.tech/docs/ru/concepts/async-replication.md?version=v25.3
  - href: en/concepts/async-replication.md
    type: text/markdown
    title: Markdown version
  - href: ../llms.txt
    type: text/markdown
    title: llms.txt
sourcePath: en/core/concepts/async-replication.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/en/llms.txt

# Asynchronous Replication

Asynchronous replication allows for synchronizing data between YDB [databases](https://ydb.tech/docs/en/concepts/glossary.md?version=v25.3#database) in near real time. It can also be used for data migration between databases with minimal downtime for applications interacting with these databases. Such databases can be located in the same YDB [cluster](https://ydb.tech/docs/en/concepts/glossary.md?version=v25.3#cluster) as well as in different clusters.

## Overview {#how-it-works}

Asynchronous replication is based on [Change Data Capture](https://ydb.tech/docs/en/concepts/cdc.md?version=v25.3) and operates on logical data. The following diagram illustrates the replication process:

```mermaid
sequenceDiagram
  participant dst as Source
  participant src as Target

  dst-->src: Initialization
  dst->>dst: Creating an asynchronous replication instance
  dst->>src: Creating changefeeds
  dst->>dst: Creating replica objects

  dst-->src: Initial table scan
  loop
    dst->>src: Request to get data
    src->>dst: Data
  end

  dst-->src: Change data replication
  loop
    dst->>src: Request to get data
    src->>dst: Data
  end
```

As shown in the diagram above, asynchronous replication involves two databases:

1. **Source**. A database with [replicated objects](https://ydb.tech/docs/en/concepts/glossary.md?version=v25.3#replicated-object).
2. **Target**. A database where an [asynchronous replication instance](https://ydb.tech/docs/en/concepts/glossary.md?version=v25.3#async-replication-instance) and [replica objects](https://ydb.tech/docs/en/concepts/glossary.md?version=v25.3#replica-object) will be created.

Asynchronous replication consists of the following stages:

* [Initialization](#init)
* [Initial table scan](#initial-scan)
* [Change data replication](#replication-of-changes)

### Initialization {#init}

Initialization of asynchronous replication includes the following steps:

* Creating an asynchronous replication instance on the target database using the [CREATE ASYNC REPLICATION](https://ydb.tech/docs/en/yql/reference/syntax/create-async-replication.md?version=v25.3) YQL expression.
* Establishing a connection with the source database. The target database connects to the source using the [connection parameters](https://ydb.tech/docs/en/yql/reference/syntax/create-async-replication.md?version=v25.3#params) specified during the creation of the asynchronous replication instance.

{% note info %}

The user account that is used to connect to the source database must have the following [permissions](https://ydb.tech/docs/en/security/short-access-control-notation.md?version=v25.3#access-rights):

* Read permissions for schema objects and directory objects
* Create, update, delete, and read permissions for changefeeds

{% endnote %}

* The following objects are created for replicated objects on the source:
  * [changefeeds](https://ydb.tech/docs/en/concepts/glossary.md?version=v25.3#changefeed) on the source
  * [replica objects](https://ydb.tech/docs/en/concepts/glossary.md?version=v25.3#replica-object) on the target

{% note info %}

Replicas are created under the user account that was used to create the asynchronous replication instance.

{% endnote %}

### Initial Table Scan {#initial-scan}

During the [initial table scan](https://ydb.tech/docs/en/concepts/cdc.md?version=v25.3#initial-scan) the source data is exported to changefeeds. The target runs [consumers](https://ydb.tech/docs/en/concepts/datamodel/topic.md?version=v25.3#consumer) that read the source data from the changefeeds and write it to replicas.

You can get the progress of the initial table scan from the [description](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-describe.md?version=v25.3) of the asynchronous replication instance.

### Change Data Replication {#replication-of-changes}

After the initial table scan is completed, the consumers read the change data and write it to replicas.

Each change data block has its *creation time* ($created\_at$). Consumers track the *reception time* of the change data ($received\_at$). Thus, you can use the following formula to calculate the *replication lag*:

$$
replication\_lag = received\_at - created\_at
$$

You can also get the replication lag from the [description](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-describe.md?version=v25.3) of the asynchronous replication instance.

## Restrictions {#restrictions}

* The set of replicated objects is immutable and is generated when YDB creates an asynchronous replication instance.
* YDB supports the following types of replicated objects:

  * [row-based tables](https://ydb.tech/docs/en/concepts/datamodel/table.md?version=v25.3#row-oriented-tables)
  * [directories](https://ydb.tech/docs/en/concepts/datamodel/dir.md?version=v25.3)

    YDB will replicate all row-based tables that are located in the given directories and subdirectories at the time the asynchronous replication instance is created.

* During asynchronous replication, you cannot [add or delete columns](https://ydb.tech/docs/en/yql/reference/syntax/alter_table/columns.md?version=v25.3) in the source tables.
* During asynchronous replication, replicas are available only for reading.

## Error Handling During Asynchronous Replication {#error-handling}

Possible errors during asynchronous replication can be grouped into the following classes:

* **Temporary failures**, such as transport errors, system overload, etc. Requests will be resent until they are processed successfully.
* **Critical errors**, such as access violation errors, schema errors, etc. Replication will be aborted, and the [description](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-describe.md?version=v25.3) of the asynchronous replication instance will include the text of the error.

{% note warning %}

Currently, asynchronous replication that is aborted due to a critical error cannot be resumed. In this case, you must [drop](https://ydb.tech/docs/en/yql/reference/syntax/drop-async-replication.md?version=v25.3) and [create](https://ydb.tech/docs/en/yql/reference/syntax/create-async-replication.md?version=v25.3) a new asynchronous replication instance.

{% endnote %}

For more information about error classes and how to address them, refer to [Error Handling](https://ydb.tech/docs/en/reference/ydb-sdk/error_handling.md?version=v25.3).

## Consistency Levels of Replicated Data {#consistency-levels}

### Row-Level Data Consistency {#consistency-level-row}

The Change Data Capture used for asynchronous replication [guarantees](https://ydb.tech/docs/en/concepts/cdc.md?version=v25.3#guarantees) that changes to the same [primary key](https://ydb.tech/docs/en/concepts/datamodel/table.md?version=v25.3) are delivered in the exact order in which they occurred at the source. This ensures row-level data consistency.

Data written to replica objects in this mode becomes available for reading immediately.

### Global Data Consistency {#consistency-level-global}

When [transactions](https://ydb.tech/docs/en/concepts/transactions.md?version=v25.3) are performed at the source, several rows in a table or even rows in different table partitions may be atomically modified. Global data consistency at the target implies preserving atomicity: changes "appear" (become available for reading) in a consistent manner.

To ensure global data consistency, changefeeds must be created with [barriers](https://ydb.tech/docs/en/concepts/cdc.md?version=v25.3#barriers) enabled. Data is buffered directly in the partitions of replica objects between barriers. When the next set of barriers from all topics is received, the changes are committed and become available for reading. As a result, the data at the target is consistent as of the timestamp specified in the barrier. If we assume that barriers are created every 10 seconds at the source (the default value), then under normal conditions the target also commits and publishes the set of changes from the source every 10 seconds.

#### Change Commit Interval {#commit-interval}

By default changes are committed no more than once every 10 seconds. You can override the change commit interval by specifying the [COMMIT_INTERVAL](https://ydb.tech/docs/en/yql/reference/syntax/create-async-replication.md?version=v25.3#params) option when creating an asynchronous replication instance.

{% note info %}

The change commit interval directly affects the barrier emission interval in the changefeed — the parameter values are synchronized. Thus, changes are usually committed at the same frequency as barriers appear in the changefeeds. However, in some cases, for example, if there is an uneven load across tables, barriers in changefeeds may appear at significantly different times, which can increase the change commit interval. You can find information about the lag in the [description](https://ydb.tech/docs/en/reference/ydb-cli/commands/scheme-describe.md?version=v25.3) of the asynchronous replication instance.

{% endnote %}

## Asynchronous Replication Completion {#done}

Completion of asynchronous replication might be an end goal of data migration from one database to another. In this case the client stops writing data to the source, waits for the zero replication lag, and completes replication. After the replication process is completed, replicas become available both for reading and writing. Then you can switch the load from the source database to the target database and complete data migration.

{% note info %}

You cannot resume completed asynchronous replication.

{% endnote %}

{% note warning %}

YDB currently supports only **forced** completion of asynchronous replication, when no additional checks are performed for data consistency, replication lag, etc.

{% endnote %}

To complete asynchronous replication, use the [ALTER ASYNC REPLICATION](https://ydb.tech/docs/en/yql/reference/syntax/alter-async-replication.md?version=v25.3) YQL expression.

## Dropping an Asynchronous Replication Instance {#drop}

When you drop an asynchronous replication instance:

* Changefeeds are deleted in the source tables.
* The source tables are unlocked, and you can add and delete columns again.
* Optionally, all replicas are deleted.
* Asynchronous replication instance is deleted.

{% note warning %}

If asynchronous replication is dropped without prior [completion](#done) and replica objects are not deleted, they will remain available only for reading.

{% endnote %}

To drop an asynchronous replication instance, use the [DROP ASYNC REPLICATION](https://ydb.tech/docs/en/yql/reference/syntax/drop-async-replication.md?version=v25.3) YQL expression.