Add ALTER EXTERNAL CONNECTION #20654
Conversation
Added a new sql reference page for ALTER EXTERNAL CONNECTION and updated relevant info on other pages
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
Typo/broken link
….com:cockroachdb/docs into 20251016-DOC-13254-alter-external-connection
❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
Another typo/broken link
Typos and example variable names
Changed parameter names to match updated diagram
….com:cockroachdb/docs into 20251016-DOC-13254-alter-external-connection
| 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. |
There was a problem hiding this comment.
| 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 to CockroachDB. When creating an external connection, you can 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. |
| 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. |
There was a problem hiding this comment.
All of the other pages in this section begin like this "The ALTER EXTERNAL CONNECTION statement..." so for the sake of consistency I'd recommend following suit.
|
|
||
| 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. |
There was a problem hiding this comment.
This sentence is long and confusing but I don't know enough about this functionality to recommend a specific change.
| 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. |
There was a problem hiding this comment.
If the "Supported external storage and sinks" table on this page is identical to the table on the "Create External Connection" page that you're linking to, I'd link instead to the table below, for the sake of keeping the reader on this page.
|
|
||
| ### 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. |
There was a problem hiding this comment.
Most of the pages in this section use the following template to explain Examples: "To [desired effect], [thing you should do]". I'd recommend following that template, as it'll allow you to avoid an awkward usage of the second person.
There was a problem hiding this comment.
I agree that it's an awkward usage of the second person here, but it follows a precedent set in CREATE EXTERNAL CONNECTION , which is the most closely related page to this one. This page is effectively a continuation of that one for anyone actually using external connections, so I think it's best to leave it this way to maintain consistency over the two pages.
| {% 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 |
There was a problem hiding this comment.
Most pages in this section end with a "See also" header. I'd recommend following suit for consistency's sake.
|
|
||
| `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 %}). |
There was a problem hiding this comment.
Same comment as above.
| @@ -0,0 +1,74 @@ | |||
| --- | |||
There was a problem hiding this comment.
Something strange is happening in the sidebar on this page, and I'm not sure why. When I go to http://localhost:4000/docs/v25.4/alter-external-connection I see "ALTER EXTERNAL CONNECTION" in the sidebar, but then when I click a different page in that section (for example, "ALTER BACKUP") the "ALTER EXTERNAL CONNECTION link in the sidebar disappears. But randomly it'll appear again if you specifically navigate to the "ALTER DATABASE" page? I'm not sure why. I haven't tested all of the pages, so I'm not sure when/why it re-appears, but this link should never disappear.
There was a problem hiding this comment.
I believe this is just a weird anomaly with local builds. If you look at the preview build linked above, it doesn't have this same bug.
There was a problem hiding this comment.
oh strange, yeah you're right about that.
Changes from doc review- all small
peachdawnleach
deleted the
20251016-DOC-13254-alter-external-connection
branch
3 participants
Addresses DOC-13254
Added a new sql reference page for ALTER EXTERNAL CONNECTION and updated relevant info on other pages