CREATE ASYNC REPLICATION

The CREATE ASYNC REPLICATION statement creates an asynchronous replication instance.

Syntax

CREATE ASYNC REPLICATION <name>
FOR <remote_path> AS <local_path> [, <another_remote_path> AS <another_local_path>]
WITH (option = value [, ...])

Parameters

name — a name of the asynchronous replication instance.
remote_path — a relative or absolute path to a table or directory in the source database.
local_path — a relative or absolute path to a target table or directory in the local database.
WITH (option = value [, ...]) — asynchronous replication parameters:
- CONNECTION_STRING — a connection string for the source database (mandatory).
- CA_CERT — a root certificate for TLS. Optional parameter. Can be specified if the source database supports an encrypted data interchange protocol (CONNECTION_STRING starts with grpcs://).
- INITIAL_SCAN: whether to perform an initial scan. An optional Bool parameter. If omitted, the server setting is used; the default is TRUE.
  - TRUE: source data is transferred through changefeeds, and replica objects are created automatically.
  - FALSE: replication is created in the PAUSED state and prepares changefeeds without an initial scan. Target tables are not created or attached to replication until it switches to STANDBY. First, back up the source and restore the data on the target, then start replication using ALTER ASYNC REPLICATION. When replication starts, target tables must exist and match the source schemas, subject to the restrictions. For the procedure, see the initial synchronization guide.
- AVAILABILITY_PERIOD: the availability period for unacknowledged changes. An optional parameter: a positive value of type Interval or the string 'UNLIMITED'. The default is 'UNLIMITED'.
  - 'UNLIMITED': changes are retained until replication acknowledges their processing.
  - Interval, for example, Interval('PT48H'): unacknowledged changes are protected from deletion for the specified period. After it expires, they may be deleted.
  This parameter can only be set when replication is created. For help choosing a value, see the comparison of retention options.
- Authentication details for the source database (mandatory) depending on the authentication method:
  - Access token:
    - TOKEN_SECRET_PATH — the secret that contains the token.
  - Login and password:
    - USER — a database user name.
    - PASSWORD_SECRET_PATH — the secret that contains the password for the source database user.
  - Delegated service account:
    - SERVICE_ACCOUNT_ID — identifier of the service account.
    - INITIAL_TOKEN_SECRET_PATH — the secret that contains the token for the service account. Used for initialization.
CONSISTENCY_LEVEL — consistency level of replicated data:
- ROW — row-level data consistency. Default mode.
- GLOBAL — global data consistency. Additionally can be specified:
  - COMMIT_INTERVAL — change commit interval in ISO 8601 format. The default value is 10 seconds.

Examples

Tip

Before creating an asynchronous replication instance, you must create a secret with authentication credentials for the source database or ensure that you have access to an existing secret.

The following statement creates an asynchronous replication instance to synchronize the original_table source table in the /Root/another_database database to the replica_table target table in the local database:

CREATE ASYNC REPLICATION my_replication_for_single_table
FOR original_table AS replica_table
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret'
);

The statement above uses the token from the my_secret secret for authentication and the grpcs://example.com:2135 endpoint to connect to the /Root/another_database database.

The following statement creates an asynchronous replication instance to replicate the source tables original_table_1 and original_table_2 to the target tables replica_table_1 and replica_table_2:

CREATE ASYNC REPLICATION my_replication_for_multiple_tables
FOR original_table_1 AS replica_table_1, original_table_2 AS replica_table_2
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret'
);

The following statement creates an asynchronous replication instance for the objects in the original_dir directory:

CREATE ASYNC REPLICATION my_replication_for_dir
FOR original_dir AS replica_dir
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret'
);

The following statement creates an asynchronous replication instance for the objects in the /Root/another_database database:

CREATE ASYNC REPLICATION my_replication_for_database
FOR `/Root/another_database` AS `/Root/my_database`
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret'
);

The following statement creates an asynchronous replication instance with a TLS root certificate specified:

CREATE ASYNC REPLICATION my_consistent_replication
FOR original_table AS replica_table
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret',
    CA_CERT = '-----BEGIN CERTIFICATE-----...'
);

The following statement creates an asynchronous replication instance in global data consistency mode (default change commit interval is 10 seconds):

CREATE ASYNC REPLICATION my_consistent_replication
FOR original_table AS replica_table
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret',
    CONSISTENCY_LEVEL = 'GLOBAL'
);

The following statement creates an asynchronous replication instance in global data consistency mode with a one-minute change commit interval:

CREATE ASYNC REPLICATION my_consistent_replication_1min_commit_interval
FOR original_table AS replica_table
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret',
    CONSISTENCY_LEVEL = 'GLOBAL',
    COMMIT_INTERVAL = Interval('PT1M')
);

The following statement creates replication with a 48-hour availability period for unacknowledged changes:

CREATE ASYNC REPLICATION my_replication_with_availability_period
FOR original_table AS replica_table
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret',
    AVAILABILITY_PERIOD = Interval('PT48H')
);

The following statement creates replication for initial synchronization using backup and restore, retaining unacknowledged changes without an age limit:

CREATE ASYNC REPLICATION my_replication_without_initial_scan
FOR original_table AS replica_table
WITH (
    CONNECTION_STRING = 'grpcs://example.com:2135/?database=/Root/another_database',
    TOKEN_SECRET_PATH = 'my_secret',
    INITIAL_SCAN = FALSE,
    AVAILABILITY_PERIOD = 'UNLIMITED'
);

Replication prepares changefeeds in the PAUSED state. Wait until they are ready, perform the backup and restore, and then switch replication to STANDBY using ALTER ASYNC REPLICATION.

CREATE ASYNC REPLICATION

Syntax

Parameters

Examples

See also

Was the article helpful?