Add ALTER EXTERNAL CONNECTION (#20654)

* ALTER EXTERNAL CONNECTION

Added a new sql reference page for ALTER EXTERNAL CONNECTION and updated relevant info on other pages

* Typo/broken link

Typo/broken link

* Another typo/broken link

Another typo/broken link

* Quick changes from review

Typos and example variable names

* Updated parameters

Changed parameter names to match updated diagram

* Changes from doc review

Changes from doc review- all small

Author: peachdawnleach

src/current/_includes/v25.4/sidebar-data/sql.json

@@ -40,6 +40,12 @@
                 "/${VERSION}/alter-default-privileges.html"
               ]
             },
+            {
+              "title": "<code>ALTER EXTERNAL CONNECTION</code>",
+              "urls": [
+                "/${VERSION}/alter-external-connection.html"
+              ]
+            },
             {
               "title": "<code>ALTER FUNCTION</code>",
               "urls": [

src/current/v25.4/alter-external-connection.md

@@ -0,0 +1,82 @@
+---
+title: ALTER EXTERNAL CONNECTION
+summary: Use the ALTER EXTERNAL CONNECTION statement to update an external connection's URI.
+toc: true
+docs_area: reference.sql
+---
+
+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. 
+
+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:
+
+- [`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 backup_bucket TO user;
+~~~
+
+## Synopsis
+
+<div>
+{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/alter_external_connection.html %}
+</div>
+
+### Parameters
+
+Parameter | Description
+----------+-------------
+`connection_name` | The name of the existing external connection.
+`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
+
+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 `backup_bucket` 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}';
+~~~
+
+## 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 %})

src/current/v25.4/create-external-connection.md

@@ -9,13 +9,16 @@ 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 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.
 
 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
 
@@ -187,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 %})

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 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.