> ## 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 EXTERNAL CONNECTION

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>;
};

You can use external connections to specify and interact with resources that are external from CockroachDB. With `CREATE EXTERNAL CONNECTION`, you define a name for an external connection while passing the provider URI and query parameters. <InternalLink path="backup">`BACKUP`</InternalLink>, <InternalLink path="restore">`RESTORE`</InternalLink>, <InternalLink path="import-into">`IMPORT INTO`</InternalLink>, <InternalLink path="export">`EXPORT`</InternalLink>, and <InternalLink path="create-changefeed">`CREATE CHANGEFEED`</InternalLink> queries can interact with the defined external connection instead of a required, provider-specific URI. As a result, you can decouple the management of the external resource from the operation in which you're using them.

`CREATE EXTERNAL CONNECTION` will validate the URI by writing, reading, and listing a test file to the external storage URI. If you're using a <InternalLink path="take-and-restore-encrypted-backups">KMS URI</InternalLink>, `CREATE EXTERNAL CONNECTION` will encrypt and decrypt a file. You'll find a `crdb_external_storage_location` file in your external storage as a result of this test. Each of the operations that access the external connection is aware of the raw URI that is parsed to configure, authenticate, and interact with the connection.

You may need to periodically rotate your authentication token for an external connection before the old token expires. For information on how to update the connection URI to use a new token, consult <InternalLink path="alter-external-connection">`ALTER EXTERNAL CONNECTION`</InternalLink>.

The [privilege model](#required-privileges) for external connections means that you can delegate the creation and usage of external connections to the necessary users or roles.

You can also use the following SQL statements to work with external connections:

* <InternalLink path="show-external-connection">`SHOW EXTERNAL CONNECTION`</InternalLink>
* <InternalLink path="show-create-external-connection">`SHOW CREATE EXTERNAL CONNECTION`</InternalLink>
* <InternalLink path="drop-external-connection">`DROP EXTERNAL CONNECTION`</InternalLink>
* <InternalLink path="alter-external-connection">`ALTER EXTERNAL CONNECTION`</InternalLink>

## Required privileges

To create an external connection, a user must have the `EXTERNALCONNECTION` <InternalLink path="security-reference/authorization#supported-privileges">system-level privilege</InternalLink>. `root` and <InternalLink path="security-reference/authorization#admin-role">`admin`</InternalLink> users have this system-level privilege by default and are capable of granting the `EXTERNALCONNECTION` system-level privilege to other users and roles with or without the <InternalLink path="grant">`GRANT OPTION`</InternalLink>.

For example:

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

To use a specific external connection during an operation, the user must also have the `USAGE` privilege on that connection:

For example:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT USAGE ON EXTERNAL CONNECTION backup_bucket TO user;
```

## Synopsis

<img src="https://mintcdn.com/cockroachlabs/Nqtj0HvOrM_ugxgN/images/sql-diagrams/v26.2/create_external_connection.svg?fit=max&auto=format&n=Nqtj0HvOrM_ugxgN&q=85&s=daa5a2e2bc876761e8dd1dd457b86345" alt="create_external_connection syntax diagram" style={{maxWidth: "100%", overflowX: "auto"}} width="715" height="37" data-path="images/sql-diagrams/v26.2/create_external_connection.svg" />

### Parameters

| Parameter         | Description                                                       |
| ----------------- | ----------------------------------------------------------------- |
| `connection_name` | The name that represents the external connection.                 |
| `connection_URI`  | The storage/sink URI that the external connection will reference. |

## Supported external storage and sinks

| Storage or sink                                                                                                             | Operation support                                |
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| <InternalLink path="changefeed-sinks#amazon-msk">Amazon MSK</InternalLink>                                                  | Changefeeds                                      |
| <InternalLink path="use-cloud-storage">Amazon S3</InternalLink>                                                             | Backups, restores, imports, exports, changefeeds |
| <InternalLink path="take-and-restore-encrypted-backups#aws-kms-uri-format">Amazon S3 KMS</InternalLink>                     | Encrypted backups                                |
| <InternalLink path="use-cloud-storage">Azure Storage</InternalLink>                                                         | Backups, restores, imports, exports, changefeeds |
| <InternalLink path="changefeed-sinks#confluent-cloud">Confluent Cloud</InternalLink>                                        | Changefeeds                                      |
| <InternalLink path="create-changefeed">Confluent Schema Registry</InternalLink>                                             | Changefeeds                                      |
| <InternalLink path="changefeed-sinks">Google Cloud Pub/Sub</InternalLink>                                                   | Changefeeds                                      |
| <InternalLink path="use-cloud-storage">Google Cloud Storage</InternalLink>                                                  | Backups, restores, imports, exports, changefeeds |
| <InternalLink path="take-and-restore-encrypted-backups#google-cloud-kms-uri-format">Google Cloud Storage KMS</InternalLink> | Encrypted backups                                |
| <InternalLink path="changefeed-sinks">HTTP(S)</InternalLink>                                                                | Changefeeds                                      |
| <InternalLink path="changefeed-sinks#kafka">Kafka</InternalLink>                                                            | Changefeeds                                      |
| <InternalLink path="use-cloud-storage">Nodelocal</InternalLink>                                                             | Backups, restores, imports, exports, changefeeds |
| <InternalLink path="set-up-physical-cluster-replication#connection-reference">PostgreSQL</InternalLink> connections         | Physical cluster replication                     |
| <InternalLink path="use-userfile-storage">Userfile</InternalLink>                                                           | Backups, restores, imports, exports, changefeeds |
| <InternalLink path="changefeed-sinks#webhook-sink">Webhook</InternalLink>                                                   | Changefeeds                                      |

For more information on authentication and forming the URI that an external connection will represent, refer to the storage or sink pages linked in the table.

### Changefeed sinks as external connections

Consider the following when you create an external connection for changefeeds:

* You can only include the query parameters and options that Kafka sinks support. Refer to the <InternalLink path="create-changefeed#options">Options</InternalLink> table and the Kafka <InternalLink path="changefeed-sinks#kafka">query parameters</InternalLink> for more detail.
* To restrict a user's access to changefeed data and sink credentials, enable the `changefeed.permissions.require_external_connection_sink.enabled` cluster setting. When you enable this setting, users with the <InternalLink path="create-changefeed#required-privileges">`CHANGEFEED` privilege</InternalLink> on a set of tables can only create changefeeds into <InternalLink path="create-external-connection">external connections</InternalLink>.

## External connection URI format

To form the external connection URI in operation statements, use the `external://` scheme followed by the name of the external connection.

For an external connection named `backup_storage`:

```
'external://backup_storage'
```

See the [examples](#create-an-external-connection-for-cloud-storage) in the next section for details on external connection creation.

## Examples

The examples in this section demonstrate some of the storage and operation options that external connections support.

### Create an external connection for cloud storage

In this example, you create an external connection for an Amazon S3 bucket that will store your backups. Then, you use the external connection to restore the backup to your cluster.

1. Define your external connection that references the S3 bucket's URI:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE EXTERNAL CONNECTION backup_bucket AS 's3://bucket name?AWS_ACCESS_KEY_ID={access key}&AWS_SECRET_ACCESS_KEY={secret access key}';
   ```

2. Verify that the new external connection was created successfully with <InternalLink path="show-create-external-connection">`SHOW CREATE EXTERNAL CONNECTION`</InternalLink>:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   SHOW CREATE ALL EXTERNAL CONNECTIONS;
   ```

   ```
   connection_name |                                                                              create_statement
   ----------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
   backup_bucket   | CREATE EXTERNAL CONNECTION 'backup_bucket' AS 's3://bucket name?AWS_ACCESS_KEY_ID={access key}&AWS_SECRET_ACCESS_KEY={secret access key}'
   ```

3. Run the backup to your S3 bucket using the external connection's name:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   BACKUP DATABASE movr INTO 'external://backup_bucket' AS OF SYSTEM TIME '-10s' WITH revision_history;
   ```

   If you are creating an external connection<InternalLink path="create-external-connection">external connection</InternalLink> with <InternalLink path="backup#query-parameters">`BACKUP` query parameters</InternalLink> or <InternalLink path="cloud-storage-authentication">authentication</InternalLink> parameters, you must pass them in uppercase otherwise you will receive an `unknown query parameters` error.

4. Use <InternalLink path="show-backup">`SHOW BACKUP`</InternalLink> to view your backups in the storage defined by the external connection:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   SHOW BACKUPS IN 'external://backup_bucket';
   ```

   ```
           path
   ------------------------
   2022/09/19-134559.68
   2022/10/10-192044.40
   (2 rows)
   ```

5. In the event that a restore is necessary, use `RESTORE` with the external connection:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   RESTORE DATABASE movr FROM LATEST IN 'external://backup_bucket';
   ```

6. When you no longer need the external connection, you can delete it with <InternalLink path="drop-external-connection">`DROP EXTERNAL CONNECTION`</InternalLink>:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   DROP EXTERNAL CONNECTION backup_bucket;
   ```

### Create an external connection for a changefeed sink

In this example, you create an external connection to a Kafka sink to which a changefeed will emit messages. When you create the external connection, you will include the necessary query parameters for your changefeed. As a result, you will only need to specify the external connection's name when creating a changefeed rather than the Kafka URI and parameters.

1. Define your external connection that references the Kafka sink URI and any <InternalLink path="changefeed-sinks#kafka">connection parameters</InternalLink>:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE EXTERNAL CONNECTION kafka_sink AS 'kafka://broker.address.com:9092?topic_prefix=bar_&tls_enabled=true&ca_cert={certificate}&sasl_enabled=true&sasl_user={sasl user}&sasl_password={url-encoded password}&sasl_mechanism=SCRAM-SHA-256';
   ```

<Note>
  If you are creating an external connection<InternalLink path="create-external-connection">external connection</InternalLink> with <InternalLink path="create-changefeed#query-parameters">`CREATE CHANGEFEED` query parameters</InternalLink>, you must pass them in lowercase otherwise you will receive an `unknown query parameters` error.
</Note>

1. Create your changefeed using the external connection's name:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE CHANGEFEED FOR TABLE movr.users INTO 'external://kafka_sink' WITH resolved;
   ```

## See also

* <InternalLink path="create-changefeed">`CREATE CHANGEFEED`</InternalLink>
* <InternalLink path="backup">`BACKUP`</InternalLink>
* <InternalLink path="restore">`RESTORE`</InternalLink>
* <InternalLink path="export">`EXPORT`</InternalLink>
* <InternalLink path="import-into">`IMPORT INTO`</InternalLink>
* <InternalLink path="drop-external-connection">`DROP EXTERNAL CONNECTION`</InternalLink>
* <InternalLink path="show-create-external-connection">`SHOW CREATE EXTERNAL CONNECTION`</InternalLink>
* <InternalLink path="alter-external-connection">`ALTER EXTERNAL CONNECTION`</InternalLink>