# CREATE LINK

The `CREATE LINK` command creates a new connection link to S3, Azure, GCS, HDFS, HTTP, Kafka, MongoDB®, or MySQL for a permitted user.

Refer to [ALTER LINK](https://docs.singlestore.com/db/v9.1/reference/sql-reference/security-management-commands/alter-link.md) to modify an existing connection link.

## Syntax

```
CREATE [OR REPLACE] LINK [IF NOT EXISTS] [db_name.]connection_name AS
{ S3 | AZURE | GCS | HDFS | HTTP | KAFKA | MONGODB | MYSQL }
CREDENTIALS 'credentials_json'
[ CONFIG 'configuration_json' ]
[ DESCRIPTION 'description' ]

```

## Remarks

* If the `OR REPLACE` clause is provided and a link with `link_name` already exists, then the `CREATE` query updates the link with the new definition (including its credentials), but preserves pipeline’s state and its cursor positions. The source type of an existing link cannot be modified using the `CREATE OR REPLACE` statement. For example, an existing S3 link `pLink` cannot be redefined as a Kafka source using `CREATE OR REPLACE LINK pLink AS KAFKA...`
* The `OR REPLACE` and `IF NOT EXISTS` clauses are mutually exclusive, i.e., they cannot be used in the same `CREATE LINK` statement.
* `db_name` is the name of the SingleStore database. It is an optional parameter. If not specified, the connection link is created in the current (context) database.
* `CONFIG` specifies non-secret configuration settings, such as region and host. Sensitive secrets must not be stored in `CONFIG`. Store all passwords, tokens, and keys in `CREDENTIALS` instead. The contents of `CONFIG` may be displayed in metadata listings, such as `SHOW LINKS` and `INFORMATION_SCHEMA.LINKS`.
* `CONFIG` and `CREDENTIALS` can be specified in either order (`CONFIG` followed by `CREDENTIALS` or `CREDENTIALS` followed by `CONFIG`).
* The `CONFIG` and `CREDENTIALS` expect JSON-formatted information. Refer to the [Examples](https://docs.singlestore.com/#UUID-aab86688-9266-30fc-505e-887c7e5d189d.md). For more configuration examples, refer to [BACKUP DATABASE](https://docs.singlestore.com/db/v9.1/reference/sql-reference/operational-commands/backup-database.md).
* `connection_name` is a user defined name of the connection link.
* Only users with the `CREATE LINK` permission can create a connection link.
* `description` specifies the details related to the connection link.
* Commands such as `BACKUP`, `RESTORE`, `CREATE PIPELINE`, and `SELECT` support connection links. Refer to any of these commands for details on the `credentials_json` and `configuration_json` clauses.
* This command causes implicit commits. Refer to [COMMIT](https://docs.singlestore.com/db/v9.1/reference/sql-reference/data-manipulation-language-dml/commit.md) for more information.
* This command can be used to create regular and encrypted HTTP links. Refer to [Using HTTP connection links](https://docs.singlestore.com/db/v9.1/reference/sql-reference/procedural-sql-reference/create-or-replace-external-function.md) for more information and examples.
* For Kafka and HTTP links, specify SSL-related files, such as CA certificates, client certificates, and private keys, as file paths. Certificate files must be accessible from every node in the cluster. The following options are supported:

  * Local files stored at the same path on every node. Use a secure file transfer method, such as `scp`, to copy the SSL files to each SingleStore node. Ensure that the files are stored at the same absolute path on every node (for example, `/var/private/ssl/ca-cert.pem`).
  * Shared network mounts, such as NFS. Mount a shared network filesystem on every node at the same mount point (for example, `/mnt/shared/ssl/`). Store the SSL files in the shared directory so that all nodes can access them without requiring individual file copies.
  * Relative file paths passed to the underlying Kafka client. For Kafka links, paths are resolved relative to the Kafka client working directory. Ensure that the files exist at the specified relative path on every node.
* For EKS IRSA support refer [Enable EKS IRSA](https://docs.singlestore.com/db/v9.1/reference/singlestore-operator-reference/enable-eks-irsa.md)
* Refer to the [Permissions Matrix](https://docs.singlestore.com/db/v9.1/reference/sql-reference/security-management-commands/permissions-matrix.md) for the required permissions.

## Examples

## AWS S3 Example

The `configuration_json` and `credentials_json` for AWS connections look like this:

```
CREDENTIALS '{
  "aws_access_key_id": "replace_with_your_access_key_id",
  "aws_secret_access_key": "replace_with_your_secret_access_key"
  [, "aws_session_token": "replace_with_your_temp_session_token"]
  [, "role_arn":"replace_with_your_role_arn"]
}'

CONFIG ‘{
  "region": "your_region",
  "endpoint_url": "http://other_endpoint"
  [,"x-amz-server-side-encryption":"<encryption_type>" [, "x-amz-server-side-encryption-aws-kms-key-id":"<optional_key>" ] |
  "x-amz-server-side-encryption-customer-algorithm":"<encryption_type>",
  "x-amz-server-side-encryption-customer-key":"<encrypted_or_unencrypted_key>",
  "x-amz-server-side-encryption-customer-key-MD5":"<key>"
  ]
}' 
```

For other options for the CONFIG clause (`disable_gunzip`, `request_payer`, and others) see [CREATE PIPELINE](https://docs.singlestore.com/db/v9.1/reference/sql-reference/pipelines-commands/create-pipeline/#UUID-e9b729f5-e821-593f-4780-33e798409694.md).

The following example demonstrates how to create an S3 connection link `product_S3` to the database `Orderdb`.

```sql
CREATE LINK Orderdb.product_S3 AS S3
CREDENTIALS '{"aws_access_key_id":"your_access_key_id",
              "aws_secret_access_key":"your_secret_access_key"}'
CONFIG '{"region":"us-east-1"}'
DESCRIPTION 'Products ordered in December';

```

## Azure Example

The `credentials_json` for Azure looks like this:

```
CREDENTIALS '{
  "account_name": "your_account_name",
  "account_key": "encrypted_key"
}';
```

The following example shows how to create an Azure connection link.

```sql
CREATE LINK [db_name.]connection_name AS AZURE
CREDENTIALS '{
  "account_name": "your_account",
  "account_key": "encrypted_key"
}';
```

For more information about Azure credentials, see [Azure Blob Pipeline Syntax](https://docs.singlestore.com/db/v9.1/reference/sql-reference/pipelines-commands/create-pipeline/#UUID-a57594c8-138d-3bb1-d25b-aebef5185c17.md).

## GCS Example

The `credentials_json` for GCS looks like this:

```
CREDENTIALS '{
  "access_id": "your_google_access_key", 
  "secret_key": "your_google_secret_key"
};
```

The following example demonstrates how to create a GCS connection link called `mylink`.

```sql
CREATE LINK mylink AS GCS CREDENTIALS '{
  "access_id": "your_google_access_key",
  "secret_key": "your_google_secret_key"
}';
```

For more information about GCS credentials, see [CREATE PIPELINE](https://docs.singlestore.com/db/v9.1/reference/sql-reference/pipelines-commands/create-pipeline/#UUID-3d2545b1-01af-49d2-1152-10626841bfb9.md).

## HDFS Example

The login for HDFS cluster is performed via a keytab file, so typically `credentials_json` is left blank and `config_json` is used. The following example demonstrates how to create an HDFS link called `mylink`:

```sql
CREATE LINK mylink AS HDFS
CREDENTIALS ''
CONFIG '{
      "hadoop.security.authentication": "kerberos",
      "kerberos.user": "user@masked_host",
      "kerberos.keytab": "/opt/software/adkeytabs/user.keytab",
      "dfs.client.use.datanode.hostname": true,
      "dfs.datanode.kerberos.principal": "hdfs/_HOST@masked_host",
      "dfs.namenode.kerberos.principal": "hdfs/_HOST@masked_host"       
}';
```

For more information about HDFS credentials, see [Advanced HDFS Pipeline Mode](https://docs.singlestore.com/db/v9.1/load-data/data-sources/load-data-from-hdfs-using-a-pipeline/enabling-wire-encryption-and-kerberos-on-hdfs-pipelines.md).

## HTTP Example

The following example demonstrates how to create an HTTP link.

```sql
CREATE LINK test AS HTTP CREDENTIALS '{"headers": {"Authorization": "Basic cm9vdDp0ZXN0aW5nCg=="}}';
```

Refer to [Using HTTP connection links](https://docs.singlestore.com/db/v9.1/reference/sql-reference/procedural-sql-reference/create-or-replace-external-function.md) for more information and examples.

## Kafka Example

The `credentials_json` and `config_json` for Kafka can be complex. See [CREATE PIPELINE](https://docs.singlestore.com/db/v9.1/reference/sql-reference/pipelines-commands/create-pipeline/#UUID-4605223c-017e-44d6-7b51-ec3b59137e07.md) for more information.

The following example demonstrates how to create a Kafka connection link for Confluent Cloud.

```sql
CREATE LINK mylink AS KAFKA
CONFIG '{
  "security.protocol": "sasl_ssl",
  "sasl.mechanism": "PLAIN"
}'
CREDENTIALS '{
  "sasl.username": "your_sasl_username",
  "sasl.password": "your_sasl_secret_key"
}';
```

## MongoDB® Example

Here's a sample syntax to create a link to a MongoDB® endpoint:

```sql
CREATE LINK <linkname> AS MONGODB
CONFIG '{
  "mongodb.hosts":"<Hostname>",
  "collection.include.list": "<Collection list>",
  "mongodb.ssl.enabled":"true",
  "mongodb.authsource":"admin"}'
CREDENTIALS '{
  "mongodb.user":"<username>",
  "mongodb.password":"<password>"}';
```

For more information, refer to [Replicate Data from MongoDB®](https://docs.singlestore.com/db/v9.1/load-data/data-sources/replicate-data-from-mongodb.md).

## MySQL Example

Here's a sample syntax to create a link to a MySQL endpoint:

```sql
CREATE LINK <linkname> AS MYSQL 
CONFIG '{
  "database.hostname": "<Hostname>", 
  "database.exclude.list": "<database_list>", 
  "database.port": 3306, 
  "database.ssl.mode":"required"}' 
CREDENTIALS '{
  "database.password": "<password>", 
  "database.user": "<username>"}';
```

For more information, refer to [Replicate Data from MySQL](https://docs.singlestore.com/db/v9.1/load-data/data-sources/replicate-data-from-mysql.md).

## Update an Existing Link

The following example demonstrates how to use the `OR REPLACE` clause to update an existing connection link.

Create an S3 connection link called `analytics_link`:

```sql
CREATE LINK analytics_link AS S3                                              
  CREDENTIALS '{"aws_access_key_id":"original_key_id",                          
  "aws_secret_access_key":"original_secret_access_key"}'                               
  CONFIG '{"region":"us-west-1"}'                                               
  DESCRIPTION 'Analytics data storage';
```

If the credentials or configuration need to be updated, use `CREATE OR REPLACE` to modify the link:

```sql
CREATE OR REPLACE LINK analytics_link AS S3                                   
  CREDENTIALS '{"aws_access_key_id":"updated_key_id",                           
  "aws_secret_access_key":"updated_secret_access_key"}'                                
  CONFIG '{"region":"us-east-1"}'                                               
  DESCRIPTION 'Updated analytics data storage in new region'; 
```

The `CREATE OR REPLACE` statement updates the credentials and configuration for `analytics_link`. Any pipelines or operations using this link continue to function with the updated connection details, and their cursor positions are preserved.

***

Modified at: June 11, 2026

Source: [/db/v9.1/reference/sql-reference/security-management-commands/create-link/](https://docs.singlestore.com/db/v9.1/reference/sql-reference/security-management-commands/create-link/)

(An index of the documentation is available at /llms.txt)