> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CREATE LOGICALLY REPLICATED

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

<Note>
  **This feature is in <InternalLink path="cockroachdb-feature-availability">preview</InternalLink>** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).
</Note>

Logical data replication is only supported in CockroachDB self-hosted clusters.

New in v25.1: The `CREATE LOGICALLY REPLICATED` statement starts <InternalLink path="logical-data-replication-overview">**logical data replication (LDR)**</InternalLink> on a table(s) that runs between a source and destination cluster in an active-active setup. `CREATE LOGICALLY REPLICATED` creates the new table on the destination cluster automatically and conducts a fast, offline initial scan. It accepts [`unidirectional`](#unidirectional) or [`bidirectional on`](#bidirectional) as an option to create either one of the setups automatically.

Once the offline initial scan completes, the new table will come online and is ready to serve queries. In a <InternalLink path="logical-data-replication-overview#use-cases">bidirectional</InternalLink> setup, the second LDR stream will also initialize after the offline initial scan completes.

<Danger>
  If the table to be replicated contains <InternalLink path="enum">user-defined types</InternalLink>, you must use the <InternalLink path="create-logical-replication-stream">`CREATE LOGICAL REPLICATION STREAM`</InternalLink> statement instead. You can set up unidirectional or bidirectional LDR manually with `CREATE LOGICAL REPLICATION STREAM`.
</Danger>

This page is a reference for the `CREATE LOGICALLY REPLICATED` SQL statement, which includes information on its parameters and options. For a step-by-step guide to set up LDR, refer to the <InternalLink path="set-up-logical-data-replication">Set Up Logical Data Replication</InternalLink> page.

## Required privileges

`CREATE LOGICALLY REPLICATED` requires one of the following privileges:

* The <InternalLink path="security-reference/authorization#admin-role">`admin` role</InternalLink>.
* The <InternalLink path="security-reference/authorization#privileges">`REPLICATION` system privilege</InternalLink>.

Use the <InternalLink path="grant">`GRANT SYSTEM`</InternalLink> statement:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SYSTEM REPLICATION TO user;
```

## Synopsis

\<?xml version="1.0" encoding="UTF-8"?>

### Parameters

| Parameter                                  | Description                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `db_object_name`                           | The <InternalLink path="sql-name-resolution">fully qualified</InternalLink> name of the table on the source or destination cluster. Refer to [Examples](#examples).                                                                                                                                                                                           |
| `logical_replication_resources_list`       | A list of the <InternalLink path="sql-name-resolution">fully qualified</InternalLink> table names on the source or destination cluster to include in the LDR stream. Refer to the [LDR with multiple tables](#multiple-tables) example.                                                                                                                       |
| `source_connection_string`                 | The connection string to the source cluster. Use an <InternalLink path="create-external-connection">external connection</InternalLink> to store the source cluster's connection URI. To start LDR, run `CREATE LOGICALLY REPLICATED` from the destination cluster.                                                                                            |
| `logical_replication_create_table_options` | Options to modify the behavior of the LDR stream. For a list, refer to [Options](#options). **Note:** `bidirectional on` or `unidirectional`is a required option. For use cases of unidirectional and bidirectional LDR, refer to the <InternalLink path="logical-data-replication-overview#use-cases">Logical Data Replication Overview</InternalLink> page. |

## Options

| Option                                | Description                                                                                                                                                                                                                                                                        |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `bidirectional on` / `unidirectional` | (**Required**) Specifies whether the LDR stream will be unidirectional or bidirectional. With `bidirectional on` specified, LDR will set up two LDR streams between the clusters. Refer to the examples for [unidirectional](#unidirectional) and [bidirectional](#bidirectional). |
| `label`                               | Tracks LDR metrics at the job level. Add a user-specified string with `label`. For more details, refer to <InternalLink path="logical-data-replication-monitoring#metrics-labels">Metrics labels</InternalLink>.                                                                   |

## Examples

`CREATE LOGICALLY REPLICATED` will automatically create the specified source tables on the destination cluster. For unidirectional and bidirectional, run the statement to start LDR on the destination cluster that does not contain the tables.

### Unidirectional

From the destination cluster of the LDR stream, run:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE LOGICALLY REPLICATED TABLE {database.public.destination_table_name} FROM TABLE {database.public.source_table_name} ON 'external://source' WITH unidirectional;
```

Include the following:

* <InternalLink path="sql-name-resolution">Fully qualified</InternalLink> destination table name.
* <InternalLink path="sql-name-resolution">Fully qualified</InternalLink> source table name.
* <InternalLink path="create-external-connection">External connection</InternalLink> for the source cluster. For instructions on creating the external connection for LDR, refer to <InternalLink path="set-up-logical-data-replication#step-2-connect-from-the-destination-to-the-source">Set Up Logical Data Replication</InternalLink>.
* `unidirectional` option.
* Any other [options](#options).

For details on managing schema changes, conflicts, and jobs when LDR is running, refer to the <InternalLink path="manage-logical-data-replication">Manage Logical Data Replication</InternalLink> page.

### Bidirectional

Both clusters will act as a source and destination in bidirectional LDR setups. To start the LDR jobs, you must run this statement from the destination cluster that does not contain the tables:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE LOGICALLY REPLICATED TABLE {database.public.destination_table_name} FROM TABLE {database.public.source_table_name} ON 'external://source' WITH bidirectional ON 'external://destination';
```

Include the following:

* <InternalLink path="sql-name-resolution">Fully qualified</InternalLink> destination table name.
* <InternalLink path="sql-name-resolution">Fully qualified</InternalLink> source table name.
* <InternalLink path="create-external-connection">External connection</InternalLink> for the source cluster. For instructions on creating the external connection for LDR, refer to <InternalLink path="set-up-logical-data-replication#step-2-connect-from-the-destination-to-the-source">Set Up Logical Data Replication</InternalLink>.
* `bidirectional on` option defining the external connection for the destination cluster.
* Any other [options](#options).

For details on managing schema changes, conflicts, and jobs when LDR is running, refer to the <InternalLink path="manage-logical-data-replication">Manage Logical Data Replication</InternalLink> page.

### Multiple tables

To include multiple tables in an LDR stream, add the fully qualified table names in a list format. Ensure that the table name in the source table list and destination table list are in the same order:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE LOGICALLY REPLICATED TABLES ({database.public.destination_table_name_1}, {database.public.destination_table_name_2}) FROM TABLES ({database.public.source_table_name_1}, {database.public.source_table_name_2}) ON 'external://source' WITH bidirectional ON 'external://destination';
```

For details on managing schema changes, conflicts, and jobs when LDR is running, refer to the <InternalLink path="manage-logical-data-replication">Manage Logical Data Replication</InternalLink> page.

## See more

* <InternalLink path="show-logical-replication-jobs">`SHOW LOGICAL REPLICATION JOBS`</InternalLink>