ALTER EXTERNAL CONNECTION

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

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,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
+
+<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
+----------+-------------
+`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}';
+~~~

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 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:
 
 - [`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
 

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.