Skip to content

Commit c6c4daf

Browse files
author
katmayb
committed
Add docs for check external connection
1 parent d610379 commit c6c4daf

File tree

3 files changed

+180
-0
lines changed

3 files changed

+180
-0
lines changed

‎src/current/_includes/v25.2/sidebar-data/sql.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -166,6 +166,12 @@
166166
"/${VERSION}/cancel-session.html"
167167
]
168168
},
169+
{
170+
"title": "<code>CHECK EXTERNAL CONNECTION</code>",
171+
"urls": [
172+
"/${VERSION}/check-external-connection.html"
173+
]
174+
},
169175
{
170176
"title": "<code>COMMENT ON</code>",
171177
"urls": [

‎src/current/v25.1/check-external-connection.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: CHECK EXTERNAL CONNECTION
3+
summary: Test the connection of each node to your cloud storage location.
4+
toc: true
5+
---
6+
7+
{% 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 tests run as well as the size of the file to write and read for each test.
8+
9+
{{site.data.alerts.callout_info}}
10+
`CHECK EXTERNAL CONNECTION` supports testing the connection to [**cloud storage**]({% link {{ page.version.version }}/use-cloud-storage.md %}) locations.
11+
{{site.data.alerts.end}}
12+
13+
## Synopsis
14+
15+
<div>
16+
{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/check_external_connection.html %}
17+
</div>
18+
19+
## Options
20+
21+
Option | Value | Description
22+
--------+-------+------------
23+
`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.
24+
`time` | `STRING` | Run the test repeatedly until the duration has elapsed.
25+
`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.
26+
27+
## Responses
28+
29+
Field | Value | Description
30+
------|-------|------------
31+
`node` | `INT` | The node ID.
32+
`locality` | `STRING` | The [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) of the node.
33+
`ok` | `BOOL` | The success of the test run.
34+
`error` | `STRING` | Errors encountered during the test run.
35+
`transferred` | `STRING` | The size of the file transferred during the test.
36+
`read_speed` | `STRING` | The speed at which the node read the test file.
37+
`write_speed` | `STRING` | The speed at which the node wrote the test file.
38+
`can_delete` | `BOOL` | The success of file deletion.
39+
40+
## Examples
41+
42+
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 %}):
43+
44+
{% include_cached copy-clipboard.html %}
45+
~~~ sql
46+
CHECK EXTERNAL CONNECTION 'external://cloud-storage';
47+
~~~
48+
49+
~~~
50+
node | locality | ok | error | transferred | read_speed | write_speed | can_delete
51+
-------+-------------------------------------------+----+-------+-------------+-------------+-------------+-------------
52+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 66.17 MiB/s | 37.52 MiB/s | t
53+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 41.77 MiB/s | 33.55 MiB/s | t
54+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 14.23 MiB/s | 37.12 MiB/s | t
55+
~~~
56+
57+
To modify the testing parameters, use one or a combination of the options: `concurrently`, `time`, and `transfer`. For details on each, refer to [Options](#options).
58+
59+
{% include_cached copy-clipboard.html %}
60+
~~~ sql
61+
CHECK EXTERNAL CONNECTION 'external://cloud-storage' WITH transfer = '50MiB', concurrently = 5, time = '1ms';
62+
~~~
63+
~~~
64+
node | locality | ok | error | transferred | read_speed | write_speed | can_delete
65+
-------+-------------------------------------------+----+-------+-------------+-------------+-------------+-------------
66+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.85 MiB/s | 34.99 MiB/s | t
67+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.26 MiB/s | 34.91 MiB/s | t
68+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.69 MiB/s | 32.30 MiB/s | t
69+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.51 MiB/s | 33.02 MiB/s | t
70+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.29 MiB/s | 31.45 MiB/s | t
71+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.61 MiB/s | 32.58 MiB/s | t
72+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 61.04 MiB/s | 29.63 MiB/s | t
73+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 47.69 MiB/s | 34.04 MiB/s | t
74+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.66 MiB/s | 30.39 MiB/s | t
75+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.77 MiB/s | 29.64 MiB/s | t
76+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 44.95 MiB/s | 34.41 MiB/s | t
77+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 46.77 MiB/s | 33.31 MiB/s | t
78+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.64 MiB/s | 28.96 MiB/s | t
79+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.99 MiB/s | 26.65 MiB/s | t
80+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 15.14 MiB/s | 33.45 MiB/s | t
81+
~~~
82+
83+
## See also
84+
85+
- [Use Cloud Storage]({% link {{ page.version.version }}/use-cloud-storage.md %})
86+
- [Backup and Restore Overview]({% link {{ page.version.version }}/backup-and-restore-overview.md %})
87+
- [`CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/create-external-connection.md %})

‎src/current/v25.2/check-external-connection.md

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: CHECK EXTERNAL CONNECTION
3+
summary: Test the connection of each node to your cloud storage location.
4+
toc: true
5+
---
6+
7+
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 tests run as well as the size of the file to write and read for each test.
8+
9+
{{site.data.alerts.callout_info}}
10+
`CHECK EXTERNAL CONNECTION` supports testing the connection to [**cloud storage**]({% link {{ page.version.version }}/use-cloud-storage.md %}) locations.
11+
{{site.data.alerts.end}}
12+
13+
## Synopsis
14+
15+
<div>
16+
{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/check_external_connection.html %}
17+
</div>
18+
19+
## Options
20+
21+
Option | Value | Description
22+
--------+-------+------------
23+
`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.
24+
`time` | `STRING` | Run the test repeatedly until the duration has elapsed.
25+
`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.
26+
27+
## Responses
28+
29+
Field | Value | Description
30+
------|-------|------------
31+
`node` | `INT` | The node ID.
32+
`locality` | `STRING` | The [locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality) of the node.
33+
`ok` | `BOOL` | The success of the test run.
34+
`error` | `STRING` | Errors encountered during the test run.
35+
`transferred` | `STRING` | The size of the file transferred during the test.
36+
`read_speed` | `STRING` | The speed at which the node read the test file.
37+
`write_speed` | `STRING` | The speed at which the node wrote the test file.
38+
`can_delete` | `BOOL` | The success of file deletion.
39+
40+
## Examples
41+
42+
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 %}):
43+
44+
{% include_cached copy-clipboard.html %}
45+
~~~ sql
46+
CHECK EXTERNAL CONNECTION 'external://cloud-storage';
47+
~~~
48+
49+
~~~
50+
node | locality | ok | error | transferred | read_speed | write_speed | can_delete
51+
-------+-------------------------------------------+----+-------+-------------+-------------+-------------+-------------
52+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 66.17 MiB/s | 37.52 MiB/s | t
53+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 41.77 MiB/s | 33.55 MiB/s | t
54+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 32 MiB | 14.23 MiB/s | 37.12 MiB/s | t
55+
~~~
56+
57+
To modify the testing parameters, use one or a combination of the options: `concurrently`, `time`, and `transfer`. For details on each, refer to [Options](#options).
58+
59+
{% include_cached copy-clipboard.html %}
60+
~~~ sql
61+
CHECK EXTERNAL CONNECTION 'external://cloud-storage' WITH transfer = '50MiB', concurrently = 5, time = '1ms';
62+
~~~
63+
~~~
64+
node | locality | ok | error | transferred | read_speed | write_speed | can_delete
65+
-------+-------------------------------------------+----+-------+-------------+-------------+-------------+-------------
66+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.85 MiB/s | 34.99 MiB/s | t
67+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.26 MiB/s | 34.91 MiB/s | t
68+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.69 MiB/s | 32.30 MiB/s | t
69+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.51 MiB/s | 33.02 MiB/s | t
70+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 59.29 MiB/s | 31.45 MiB/s | t
71+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.61 MiB/s | 32.58 MiB/s | t
72+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 61.04 MiB/s | 29.63 MiB/s | t
73+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 47.69 MiB/s | 34.04 MiB/s | t
74+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 55.66 MiB/s | 30.39 MiB/s | t
75+
1 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.77 MiB/s | 29.64 MiB/s | t
76+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 44.95 MiB/s | 34.41 MiB/s | t
77+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 46.77 MiB/s | 33.31 MiB/s | t
78+
2 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 57.64 MiB/s | 28.96 MiB/s | t
79+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 58.99 MiB/s | 26.65 MiB/s | t
80+
3 | cloud=gce,region=us-east1,zone=us-east1-b | t | | 50 MiB | 15.14 MiB/s | 33.45 MiB/s | t
81+
~~~
82+
83+
## See also
84+
85+
- [Use Cloud Storage]({% link {{ page.version.version }}/use-cloud-storage.md %})
86+
- [Backup and Restore Overview]({% link {{ page.version.version }}/backup-and-restore-overview.md %})
87+
- [`CREATE EXTERNAL CONNECTION`]({% link {{ page.version.version }}/create-external-connection.md %})

0 commit comments

Comments
 (0)