From 9fc21a9fe9589179a59679e1d61db2d1f45947ca Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Thu, 16 Oct 2025 17:06:51 -0400 Subject: [PATCH 1/6] ALTER EXTERNAL CONNECTION Added a new sql reference page for ALTER EXTERNAL CONNECTION and updated relevant info on other pages --- .../_includes/v25.4/sidebar-data/sql.json | 6 ++ .../v25.4/alter-external-connection.md | 74 +++++++++++++++++++ .../v25.4/create-external-connection.md | 3 + src/current/v25.4/sql-statements.md | 1 + 4 files changed, 84 insertions(+) create mode 100644 src/current/v25.4/alter-external-connection.md diff --git a/src/current/_includes/v25.4/sidebar-data/sql.json b/src/current/_includes/v25.4/sidebar-data/sql.json index e2bd29ee86e..be1452e3715 100644 --- a/src/current/_includes/v25.4/sidebar-data/sql.json +++ b/src/current/_includes/v25.4/sidebar-data/sql.json @@ -40,6 +40,12 @@ "/${VERSION}/alter-default-privileges.html" ] }, + { + "title": "ALTER EXTERNAL CONNECTION", + "urls": [ + "/${VERSION}/alter-external-connection.html" + ] + }, { "title": "ALTER FUNCTION", "urls": [ diff --git a/src/current/v25.4/alter-external-connection.md b/src/current/v25.4/alter-external-connection.md new file mode 100644 index 00000000000..34e79c0c0e0 --- /dev/null +++ b/src/current/v25.4/alter-external-connection.md @@ -0,0 +1,74 @@ +--- +title: ALTER EXTERNAL CONNECTION +summary: Use the ALTER EXTERNAL CONNECTION statement to update an external conection's URI. +toc: true +docs_area: reference.sql +--- + +You can use external connections to specify and interact with resources that are external from CockroachDB. When creating an external connection, you define a name for an external connection while passing the provider URI and query parameters. `ALTER EXTERNAL CONNECTION` allows you to change the [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}/#supported-external-storage-and-sinks) URI that an external connection references. + +Use `ALTER EXTERNAL CONNECTION` to rotate your authentication token for an external connection by updating the connection string for the external connection to use a new auth token before the old auth token expires. + +You can also use the following SQL statements to work with external connections: + +- [`CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/create-external-connection.md %}) +- [`SHOW EXTERNAL CONNECTION`]({% link {{ page.version.version }}/show-external-connection.md %}) +- [`SHOW CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/show-create-external-connection.md %}) +- [`DROP EXTERNAL CONNECTION`]({% link {{ page.version.version }}/drop-external-connection.md %}) + +## Required privileges + +To update an external connection, a user must have the `UPDATE` privilege on that connection. + +For example: + +{% include_cached copy-clipboard.html %} +~~~sql +GRANT UPDATE ON EXTERNAL CONNECTION example_conn TO user; +~~~ + +## Synopsis + +
+{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/alter_external_connection.html %} +
+ +### Parameters + +Parameter | Description +----------+------------- +`label_spec` | The name of the existing external connection. +`string_or_placeholder` | The new [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}/#supported-external-storage-and-sinks) URI that the external connection will be updated to reference. + +## Supported external storage and sinks + +Storage or sink | Operation support +---------------------+--------------------------------- +[Amazon MSK]({% link {{ page.version.version }}/changefeed-sinks.md %}#amazon-msk) | Changefeeds +[Amazon S3]({% link {{ page.version.version }}/use-cloud-storage.md %}) | Backups, restores, imports, exports, changefeeds +[Amazon S3 KMS]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#aws-kms-uri-format) | Encrypted backups +[Azure Storage]({% link {{ page.version.version }}/use-cloud-storage.md %}) | Backups, restores, imports, exports, changefeeds +[Confluent Cloud]({% link {{ page.version.version }}/changefeed-sinks.md %}#confluent-cloud) | Changefeeds +[Confluent Schema Registry]({% link {{ page.version.version }}/create-changefeed.md %}#confluent-schema-registry) | Changefeeds +[Google Cloud Pub/Sub]({% link {{ page.version.version }}/changefeed-sinks.md %}#google-cloud-pub-sub) | Changefeeds +[Google Cloud Storage]({% link {{ page.version.version }}/use-cloud-storage.md %}) | Backups, restores, imports, exports, changefeeds +[Google Cloud Storage KMS]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}#google-cloud-kms-uri-format) | Encrypted backups +[HTTP(S)]({% link {{ page.version.version }}/changefeed-sinks.md %}) | Changefeeds +[Kafka]({% link {{ page.version.version }}/changefeed-sinks.md %}#kafka) | Changefeeds +[Nodelocal]({% link {{ page.version.version }}/use-cloud-storage.md %}) | Backups, restores, imports, exports, changefeeds +[PostgreSQL]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#connection-reference) connections | Physical cluster replication +[Userfile]({% link {{ page.version.version }}/use-userfile-storage.md %}) | Backups, restores, imports, exports, changefeeds +[Webhook]({% link {{ page.version.version }}/changefeed-sinks.md %}#webhook-sink) | 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. + +## Examples + +### Update the URI of an external connection + +In this example, you update the `backupbucket` external connection to a new Amazon S3 URI to rotate your auth token. + +{% include_cached copy-clipboard.html %} +~~~sql +ALTER EXTERNAL CONNECTION backup_bucket AS 's3://bucket name?AWS_ACCESS_KEY_ID={new access key}&AWS_SECRET_ACCESS_KEY={new secret access key}'; +~~~ \ No newline at end of file diff --git a/src/current/v25.4/create-external-connection.md b/src/current/v25.4/create-external-connection.md index ba06ef057de..9ece1696650 100644 --- a/src/current/v25.4/create-external-connection.md +++ b/src/current/v25.4/create-external-connection.md @@ -9,6 +9,8 @@ You can use external connections to specify and interact with resources that are `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 [KMS URI]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}), `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 by updating the URI for the connection to use a new auth token before the old auth token expires. For information on how to do this, consult [`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %}). + 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: @@ -16,6 +18,7 @@ You can also use the following SQL statements to work with external connections: - [`SHOW EXTERNAL CONNECTION`]({% link {{ page.version.version }}/show-external-connection.md %}) - [`SHOW CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/show-create-external-connection.md %}) - [`DROP EXTERNAL CONNECTION`]({% link {{ page.version.version }}/drop-external-connection.md %}) +- [`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %}) ## Required privileges diff --git a/src/current/v25.4/sql-statements.md b/src/current/v25.4/sql-statements.md index 8a5fbf3a1db..b3d65f68c8a 100644 --- a/src/current/v25.4/sql-statements.md +++ b/src/current/v25.4/sql-statements.md @@ -15,6 +15,7 @@ Statement | Usage ----------|------------ [`ALTER DATABASE`]({% link {{ page.version.version }}/alter-database.md %}) | Apply a schema change to a database. [`ALTER DEFAULT PRIVILEGES`]({% link {{ page.version.version }}/alter-default-privileges.md %}) | Change the default [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#privileges) for objects created by specific roles/users in the current database. +[`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %}) | Update an external conection's URI. [`ALTER FUNCTION`]({% link {{ page.version.version }}/alter-function.md %}) | Modify a [user-defined function]({% link {{ page.version.version }}/user-defined-functions.md %}). [`ALTER INDEX`]({% link {{ page.version.version }}/alter-index.md %}) | Apply a schema change to an index. [`ALTER PARTITION`]({% link {{ page.version.version }}/alter-partition.md %}) | Configure the replication zone for a partition. From a6100879c8d61a571603ebd87eb8fe57a0a8c634 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Fri, 17 Oct 2025 13:31:51 -0400 Subject: [PATCH 2/6] Typo/broken link Typo/broken link --- src/current/v25.4/alter-external-connection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v25.4/alter-external-connection.md b/src/current/v25.4/alter-external-connection.md index 34e79c0c0e0..576580a303b 100644 --- a/src/current/v25.4/alter-external-connection.md +++ b/src/current/v25.4/alter-external-connection.md @@ -5,7 +5,7 @@ toc: true docs_area: reference.sql --- -You can use external connections to specify and interact with resources that are external from CockroachDB. When creating an external connection, you define a name for an external connection while passing the provider URI and query parameters. `ALTER EXTERNAL CONNECTION` allows you to change the [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}/#supported-external-storage-and-sinks) URI that an external connection references. +You can use external connections to specify and interact with resources that are external from CockroachDB. When creating an external connection, you define a name for an external connection while passing the provider URI and query parameters. `ALTER EXTERNAL CONNECTION` allows you to change the [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}#supported-external-storage-and-sinks) URI that an external connection references. Use `ALTER EXTERNAL CONNECTION` to rotate your authentication token for an external connection by updating the connection string for the external connection to use a new auth token before the old auth token expires. From 7c1f1e293939950aa1783b261e29beecd83322e3 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Fri, 17 Oct 2025 14:11:25 -0400 Subject: [PATCH 3/6] Another typo/broken link Another typo/broken link --- src/current/v25.4/alter-external-connection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/v25.4/alter-external-connection.md b/src/current/v25.4/alter-external-connection.md index 576580a303b..8f54e569c72 100644 --- a/src/current/v25.4/alter-external-connection.md +++ b/src/current/v25.4/alter-external-connection.md @@ -38,7 +38,7 @@ GRANT UPDATE ON EXTERNAL CONNECTION example_conn TO user; Parameter | Description ----------+------------- `label_spec` | The name of the existing external connection. -`string_or_placeholder` | The new [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}/#supported-external-storage-and-sinks) URI that the external connection will be updated to reference. +`string_or_placeholder` | The new [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}#supported-external-storage-and-sinks) URI that the external connection will be updated to reference. ## Supported external storage and sinks From 80b3db97d32ffeebe5ccdcce994bc88621676584 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 21 Oct 2025 15:11:32 -0400 Subject: [PATCH 4/6] Quick changes from review Typos and example variable names --- src/current/v25.4/alter-external-connection.md | 6 +++--- src/current/v25.4/sql-statements.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/current/v25.4/alter-external-connection.md b/src/current/v25.4/alter-external-connection.md index 8f54e569c72..d3f654c918d 100644 --- a/src/current/v25.4/alter-external-connection.md +++ b/src/current/v25.4/alter-external-connection.md @@ -1,6 +1,6 @@ --- title: ALTER EXTERNAL CONNECTION -summary: Use the ALTER EXTERNAL CONNECTION statement to update an external conection's URI. +summary: Use the ALTER EXTERNAL CONNECTION statement to update an external connection's URI. toc: true docs_area: reference.sql --- @@ -24,7 +24,7 @@ For example: {% include_cached copy-clipboard.html %} ~~~sql -GRANT UPDATE ON EXTERNAL CONNECTION example_conn TO user; +GRANT UPDATE ON EXTERNAL CONNECTION backup_bucket TO user; ~~~ ## Synopsis @@ -66,7 +66,7 @@ For more information on authentication and forming the URI that an external conn ### Update the URI of an external connection -In this example, you update the `backupbucket` external connection to a new Amazon S3 URI to rotate your auth token. +In this example, you update the `backup_bucket` external connection to a new Amazon S3 URI to rotate your auth token. {% include_cached copy-clipboard.html %} ~~~sql diff --git a/src/current/v25.4/sql-statements.md b/src/current/v25.4/sql-statements.md index b3d65f68c8a..9efb6365296 100644 --- a/src/current/v25.4/sql-statements.md +++ b/src/current/v25.4/sql-statements.md @@ -15,7 +15,7 @@ Statement | Usage ----------|------------ [`ALTER DATABASE`]({% link {{ page.version.version }}/alter-database.md %}) | Apply a schema change to a database. [`ALTER DEFAULT PRIVILEGES`]({% link {{ page.version.version }}/alter-default-privileges.md %}) | Change the default [privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#privileges) for objects created by specific roles/users in the current database. -[`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %}) | Update an external conection's URI. +[`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %}) | Update an external connection's URI. [`ALTER FUNCTION`]({% link {{ page.version.version }}/alter-function.md %}) | Modify a [user-defined function]({% link {{ page.version.version }}/user-defined-functions.md %}). [`ALTER INDEX`]({% link {{ page.version.version }}/alter-index.md %}) | Apply a schema change to an index. [`ALTER PARTITION`]({% link {{ page.version.version }}/alter-partition.md %}) | Configure the replication zone for a partition. From 601103e77ce573a5f5a182931aef56ef820d5263 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Tue, 21 Oct 2025 15:17:08 -0400 Subject: [PATCH 5/6] Updated parameters Changed parameter names to match updated diagram --- src/current/v25.4/alter-external-connection.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/v25.4/alter-external-connection.md b/src/current/v25.4/alter-external-connection.md index d3f654c918d..d8e20afcf45 100644 --- a/src/current/v25.4/alter-external-connection.md +++ b/src/current/v25.4/alter-external-connection.md @@ -37,8 +37,8 @@ GRANT UPDATE ON EXTERNAL CONNECTION backup_bucket TO user; Parameter | Description ----------+------------- -`label_spec` | The name of the existing external connection. -`string_or_placeholder` | The new [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}#supported-external-storage-and-sinks) URI that the external connection will be updated to reference. +`connection_name` | The name of the existing external connection. +`connection_uri` | The new [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}#supported-external-storage-and-sinks) URI that the external connection will be updated to reference. ## Supported external storage and sinks From a71e6a82d6ddd8ae5e7bc38987dfbf9a9bedac26 Mon Sep 17 00:00:00 2001 From: Peach Leach Date: Wed, 22 Oct 2025 15:40:33 -0400 Subject: [PATCH 6/6] Changes from doc review Changes from doc review- all small --- src/current/v25.4/alter-external-connection.md | 16 ++++++++++++---- src/current/v25.4/create-external-connection.md | 3 ++- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/src/current/v25.4/alter-external-connection.md b/src/current/v25.4/alter-external-connection.md index d8e20afcf45..5bf1150a641 100644 --- a/src/current/v25.4/alter-external-connection.md +++ b/src/current/v25.4/alter-external-connection.md @@ -5,9 +5,11 @@ toc: true docs_area: reference.sql --- -You can use external connections to specify and interact with resources that are external from CockroachDB. When creating an external connection, you define a name for an external connection while passing the provider URI and query parameters. `ALTER EXTERNAL CONNECTION` allows you to change the [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}#supported-external-storage-and-sinks) URI that an external connection references. +The `ALTER EXTERNAL CONNECTION` [statement]({% link {{ page.version.version }}/sql-statements.md %}) allows you to change the [storage/sink](#supported-external-storage-and-sinks) URI that an external connection references. -Use `ALTER EXTERNAL CONNECTION` to rotate your authentication token for an external connection by updating the connection string for the external connection to use a new auth token before the old auth token expires. +You can use external connections to specify and interact with resources that are external to CockroachDB. When creating an external connection, you must define a name for the external connection while passing the provider URI and query parameters. + +You can use `ALTER EXTERNAL CONNECTION` to update the connection string for an external connection to use a new authentication token. This allows you to rotate your auth token before the old token expires. You can also use the following SQL statements to work with external connections: @@ -38,7 +40,7 @@ GRANT UPDATE ON EXTERNAL CONNECTION backup_bucket TO user; Parameter | Description ----------+------------- `connection_name` | The name of the existing external connection. -`connection_uri` | The new [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}#supported-external-storage-and-sinks) URI that the external connection will be updated to reference. +`connection_uri` | The new [storage/sink](#supported-external-storage-and-sinks) URI that the external connection will be updated to reference. ## Supported external storage and sinks @@ -71,4 +73,10 @@ In this example, you update the `backup_bucket` external connection to a new Ama {% include_cached copy-clipboard.html %} ~~~sql ALTER EXTERNAL CONNECTION backup_bucket AS 's3://bucket name?AWS_ACCESS_KEY_ID={new access key}&AWS_SECRET_ACCESS_KEY={new secret access key}'; -~~~ \ No newline at end of file +~~~ + +## See also + +- [`CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/create-external-connection.md %}) +- [`DROP EXTERNAL CONNECTION`]({% link {{ page.version.version }}/drop-external-connection.md %}) +- [`SHOW CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/show-create-external-connection.md %}) \ No newline at end of file diff --git a/src/current/v25.4/create-external-connection.md b/src/current/v25.4/create-external-connection.md index 9ece1696650..4e4ac1e7c3a 100644 --- a/src/current/v25.4/create-external-connection.md +++ b/src/current/v25.4/create-external-connection.md @@ -9,7 +9,7 @@ You can use external connections to specify and interact with resources that are `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 [KMS URI]({% link {{ page.version.version }}/take-and-restore-encrypted-backups.md %}), `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 by updating the URI for the connection to use a new auth token before the old auth token expires. For information on how to do this, consult [`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %}). +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 [`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %}). 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. @@ -190,3 +190,4 @@ In this example, you create an external connection to a Kafka sink to which a ch - [`IMPORT INTO`]({% link {{ page.version.version }}/import-into.md %}) - [`DROP EXTERNAL CONNECTION`]({% link {{ page.version.version }}/drop-external-connection.md %}) - [`SHOW CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/show-create-external-connection.md %}) +- [`ALTER EXTERNAL CONNECTION`]({% link {{ page.version.version }}/alter-external-connection.md %})