Add docs for check external connection #19642
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| You can test the connection from each node in the cluster to your external storage with the [`CHECK EXTERNAL CONNECTION`]({% link {{ page.version.version }}/check-external-connection.md %}) statement. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| You can test the connection from each node in the cluster to your external storage with the [`CHECK EXTERNAL CONNECTION`]({% link {{ page.version.version }}/check-external-connection.md %}) statement. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| You can test the connection from each node in the cluster to your external storage with the [`CHECK EXTERNAL CONNECTION`]({% link {{ page.version.version }}/check-external-connection.md %}) statement. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| --- | ||
| title: CHECK EXTERNAL CONNECTION | ||
| summary: Test the connection of each node to your cloud storage location. | ||
| toc: true | ||
| --- | ||
|
|
||
| {% include_cached new-in.html version="v25.1" %} The `CHECK EXTERNAL CONNECTION` tests the connection from each node in the cluster to an external cloud storage location. `CHECK EXTERNAL CONNECTION` will measure the time it takes each node to write a file, read it, and delete it from the specified storage location. You can adjust the number and concurrency of the test runs as well as the size of the file to write and read for each test. | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| You can use the `CHECK EXTERNAL CONNECTION` to test the connection to [**cloud storage**]({% link {{ page.version.version }}/use-cloud-storage.md %}) locations. | ||
| {{site.data.alerts.end}} | ||
|
|
||
| ## Synopsis | ||
|
|
||
| <div> | ||
| {% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/check_external_connection.html %} | ||
| </div> | ||
|
|
||
| ## Parameters | ||
|
|
||
| Parameter | Description | ||
| ----------+------------ | ||
| `connection_uri` | The URI to the external storage. Specify the [provider's URI]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., `gs://bucket_name?AUTH...`) or a user-defined [external connection]({% link {{ page.version.version }}/create-external-connection.md %}) (e.g., `external://gcs`). | ||
|
|
||
| ## Options | ||
|
|
||
| Option | Value | Description | ||
| --------+-------+------------ | ||
| `concurrently` | `INT` | Run multiple connection tests concurrently. If you also set the `time` option, it will run the specified number of concurrent tests until the time has elapsed. By default, only `1` connection test will run. | ||
|
There was a problem hiding this comment. i assume There was a problem hiding this comment. Yep, it's |
||
| `time` | `STRING` | Run the test repeatedly until the duration has elapsed. | ||
|
There was a problem hiding this comment. if this is an actual There was a problem hiding this comment. It's a duration string, which we don't have type docs for |
||
| `transfer` | `STRING` | The size of the file that is written and read during each iteration of the connection test. By default, this will transfer a `32MiB` file. | ||
|
There was a problem hiding this comment. was curious if we have docs somewhere on how we format file sizes in the |
||
|
|
||
| ## Responses | ||
|
|
||
| Field | Value | Description | ||
| ------|-------|------------ | ||
| `node` | `INT` | The node ID. | ||
| `locality` | `STRING` | The [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) of the node. | ||
| `ok` | `BOOL` | The success of the test run. | ||
|
There was a problem hiding this comment. small but i would find this clearer as "whether the test run succeeded" |
||
| `error` | `STRING` | Errors encountered during the test run. | ||
| `transferred` | `STRING` | The size of the file transferred during the test. | ||
| `read_speed` | `STRING` | The speed at which the node read the test file. | ||
| `write_speed` | `STRING` | The speed at which the node wrote the test file. | ||
| `can_delete` | `BOOL` | The success of file deletion. | ||
|
There was a problem hiding this comment. suggest "whether file deletion succeeded" (if accurate) |
||
|
|
||
| ## Examples | ||
|
There was a problem hiding this comment. nit: singular 'example' OR could create a subheading 'Test an external connection', which would leave room for adding examples in future if desired i slightly lean latter but either would work i think |
||
|
|
||
| Specify the connection URI to the [external storage location]({% link {{ page.version.version }}/use-cloud-storage.md %}), or a created [external connection]({% link {{ page.version.version }}/create-external-connection.md %}): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ sql | ||
| CHECK EXTERNAL CONNECTION 'external://cloud-storage'; | ||
| ~~~ | ||
|
|
||
| ~~~ | ||
| node | locality | ok | error | transferred | read_speed | write_speed | can_delete | ||
| -------+-------------------------------------------+----+-------+-------------+-------------+-------------+------------- | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 66.17 MiB/s | 37.52 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 41.77 MiB/s | 33.55 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 14.23 MiB/s | 37.12 MiB/s | t | ||
| ~~~ | ||
|
|
||
| To modify the testing parameters, use one or a combination of the options: `concurrently`, `time`, `transfer`. For details on each, refer to [Options](#options). | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ sql | ||
| CHECK EXTERNAL CONNECTION 'external://cloud-storage' WITH transfer = '50MiB', concurrently = 5, time = '1ms'; | ||
| ~~~ | ||
| ~~~ | ||
| node | locality | ok | error | transferred | read_speed | write_speed | can_delete | ||
| -------+-------------------------------------------+----+-------+-------------+-------------+-------------+------------- | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.85 MiB/s | 34.99 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.26 MiB/s | 34.91 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.69 MiB/s | 32.30 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.51 MiB/s | 33.02 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.29 MiB/s | 31.45 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.61 MiB/s | 32.58 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 61.04 MiB/s | 29.63 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 47.69 MiB/s | 34.04 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.66 MiB/s | 30.39 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.77 MiB/s | 29.64 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 44.95 MiB/s | 34.41 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 46.77 MiB/s | 33.31 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.64 MiB/s | 28.96 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.99 MiB/s | 26.65 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 15.14 MiB/s | 33.45 MiB/s | t | ||
| ~~~ | ||
|
|
||
| ## See also | ||
|
|
||
| - [Use Cloud Storage]({% link {{ page.version.version }}/use-cloud-storage.md %}) | ||
| - [Backup and Restore Overview]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) | ||
| - [`CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/create-external-connection.md %}) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,93 @@ | ||
| --- | ||
| title: CHECK EXTERNAL CONNECTION | ||
| summary: Test the connection of each node to your cloud storage location. | ||
| toc: true | ||
| --- | ||
|
|
||
| The `CHECK EXTERNAL CONNECTION` tests the connection from each node in the cluster to an external cloud storage location. `CHECK EXTERNAL CONNECTION` will measure the time it takes each node to write a file, read it, and delete it from the specified storage location. You can adjust the number and concurrency of the test runs as well as the size of the file to write and read for each test. | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| You can use the `CHECK EXTERNAL CONNECTION` to test the connection to [**cloud storage**]({% link {{ page.version.version }}/use-cloud-storage.md %}) locations. | ||
| {{site.data.alerts.end}} | ||
|
|
||
| ## Synopsis | ||
|
|
||
| <div> | ||
| {% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/check_external_connection.html %} | ||
| </div> | ||
|
|
||
| ## Parameters | ||
|
|
||
| Parameter | Description | ||
| ----------+------------ | ||
| `connection_uri` | The URI to the external storage. Specify the [provider's URI]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., `gs://bucket_name?AUTH...`) or a user-defined [external connection]({% link {{ page.version.version }}/create-external-connection.md %}) (e.g., `external://gcs`). | ||
|
|
||
| ## Options | ||
|
|
||
| Option | Value | Description | ||
| --------+-------+------------ | ||
| `concurrently` | `INT` | Run multiple connection tests concurrently. If you also set the `time` option, it will run the specified number of concurrent tests until the time has elapsed. By default, only `1` connection test will run. | ||
| `time` | `STRING` | Run the test repeatedly until the duration has elapsed. | ||
| `transfer` | `STRING` | The size of the file that is written and read during each iteration of the connection test. By default, this will transfer a `32MiB` file. | ||
|
|
||
| ## Responses | ||
|
|
||
| Field | Value | Description | ||
| ------|-------|------------ | ||
| `node` | `INT` | The node ID. | ||
| `locality` | `STRING` | The [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) of the node. | ||
| `ok` | `BOOL` | Whether the test run succeeded. | ||
| `error` | `STRING` | Errors encountered during the test run. | ||
| `transferred` | `STRING` | The size of the file transferred during the test. | ||
| `read_speed` | `STRING` | The speed at which the node read the test file. | ||
| `write_speed` | `STRING` | The speed at which the node wrote the test file. | ||
| `can_delete` | `BOOL` | Whether file deletion succeeded. | ||
|
|
||
| ## Test an external connection | ||
|
|
||
| Specify the connection URI to the [external storage location]({% link {{ page.version.version }}/use-cloud-storage.md %}), or a created [external connection]({% link {{ page.version.version }}/create-external-connection.md %}): | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ sql | ||
| CHECK EXTERNAL CONNECTION 'external://cloud-storage'; | ||
| ~~~ | ||
|
|
||
| ~~~ | ||
| node | locality | ok | error | transferred | read_speed | write_speed | can_delete | ||
| -------+-------------------------------------------+----+-------+-------------+-------------+-------------+------------- | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 66.17 MiB/s | 37.52 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 41.77 MiB/s | 33.55 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 14.23 MiB/s | 37.12 MiB/s | t | ||
| ~~~ | ||
|
|
||
| To modify the testing parameters, use one or a combination of the options: `concurrently`, `time`, `transfer`. For details on each, refer to [Options](#options). | ||
|
|
||
| {% include_cached copy-clipboard.html %} | ||
| ~~~ sql | ||
| CHECK EXTERNAL CONNECTION 'external://cloud-storage' WITH transfer = '50MiB', concurrently = 5, time = '1ms'; | ||
| ~~~ | ||
| ~~~ | ||
| node | locality | ok | error | transferred | read_speed | write_speed | can_delete | ||
| -------+-------------------------------------------+----+-------+-------------+-------------+-------------+------------- | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.85 MiB/s | 34.99 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.26 MiB/s | 34.91 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.69 MiB/s | 32.30 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.51 MiB/s | 33.02 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.29 MiB/s | 31.45 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.61 MiB/s | 32.58 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 61.04 MiB/s | 29.63 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 47.69 MiB/s | 34.04 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.66 MiB/s | 30.39 MiB/s | t | ||
| 1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.77 MiB/s | 29.64 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 44.95 MiB/s | 34.41 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 46.77 MiB/s | 33.31 MiB/s | t | ||
| 2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.64 MiB/s | 28.96 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.99 MiB/s | 26.65 MiB/s | t | ||
| 3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 15.14 MiB/s | 33.45 MiB/s | t | ||
| ~~~ | ||
|
|
||
| ## See also | ||
|
|
||
| - [Use Cloud Storage]({% link {{ page.version.version }}/use-cloud-storage.md %}) | ||
| - [Backup and Restore Overview]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) | ||
| - [`CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/create-external-connection.md %}) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Suggest adding
docs_area: reference.sqlto the frontmatter so this matches our other pages(PS i should probably go look if this still matters? ISTR Jesse was doing this for "reasons" but i no longer remember why)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I didn't think we had to use this anymore, and checked in with Mike and he confirmed it's ok to drop that in the FM.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
thanks, I filed https://cockroachlabs.atlassian.net/browse/DOC-13935 for us to remove them