Skip to content

Commit eb4a848

Browse files
katmaybkatmayb
committed
Add CHECK EXTERNAL CONNECTION SQL syntax to docs 25.1 25.2
1 parent 39a0bba commit eb4a848

14 files changed

+232
-0
lines changed

‎src/current/_includes/v25.1/backups/external-storage-check-tip.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
You can test the connection to your external storage from each node in the cluster with [`CHECK EXTERNAL CONNECTION`]({% link {{ page.version.version }}/check-external-connection.md %}).

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,12 @@
160160
"/${VERSION}/cancel-session.html"
161161
]
162162
},
163+
{
164+
"title": "<code>CHECK EXTERNAL CONNECTION</code>",
165+
"urls": [
166+
"/${VERSION}/check-external-connection.html"
167+
]
168+
},
163169
{
164170
"title": "<code>COMMENT ON</code>",
165171
"urls": [

‎src/current/_includes/v25.2/backups/external-storage-check-tip.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
You can test the connection to your external storage from each node in the cluster with [`CHECK EXTERNAL CONNECTION`]({% link {{ page.version.version }}/check-external-connection.md %}).

‎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/backup-validation.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ You can validate a backup of a [cluster]({% link {{ page.version.version }}/back
1515

1616
The options that give the most validation coverage will increase the runtime of the check. That is, `verify_backup_table_data` will take a longer time to validate a backup compared to `check_files` or `schema_only` alone. Despite that, each of these validation options provide a quicker way to validate a backup over running a "regular" restore.
1717

18+
{{site.data.alerts.callout_success}}
19+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
20+
{{site.data.alerts.end}}
21+
1822
## Recommendations
1923

2024
Cockroach Labs recommends implementing the following validation plan to test your backups:

‎src/current/v25.1/backup.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ To view the contents of an backup created with the `BACKUP` statement, use [`SHO
4444
- Modifying backup files in the storage location could invalidate a backup, and therefore, prevent a restore. In v22.1 and later, **we recommend enabling [object locking]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage) in your cloud storage bucket.**
4545
- While Cockroach Labs actively tests Amazon S3, Google Cloud Storage, and Azure Storage, we **do not** test [S3-compatible services]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., [MinIO](https://min.io/), [Red Hat Ceph](https://docs.ceph.com/en/pacific/radosgw/s3/)).
4646

47+
{{site.data.alerts.callout_success}}
48+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
49+
{{site.data.alerts.end}}
50+
4751
## Required privileges
4852

4953
{% include {{ page.version.version }}/backups/updated-backup-privileges.md %}

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

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

‎src/current/v25.1/cloud-storage-authentication.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ Cockroach Labs supports different levels of authentication to cloud storage. Whe
1111
We recommend using IAM roles for users to authenticate to cloud storage resources. For more detail, see the assume role and workload identity sections for [Amazon S3]({% link {{ page.version.version }}/cloud-storage-authentication.md %}#set-up-amazon-s3-assume-role) and [Google Cloud Storage](cloud-storage-authentication.html?filters=gcs#set-up-google-cloud-storage-assume-role).
1212
{{site.data.alerts.end}}
1313

14+
{{site.data.alerts.callout_success}}
15+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
16+
{{site.data.alerts.end}}
17+
1418
<div class="filters clearfix">
1519
<button class="filter-button" data-scope="s3">Amazon S3</button>
1620
<button class="filter-button" data-scope="gcs">Google Cloud Storage</button>

‎src/current/v25.1/use-cloud-storage.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ You can disable the use of implicit credentials when accessing external cloud st
5959

6060
### Example file URLs
6161

62+
{{site.data.alerts.callout_success}}
63+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
64+
{{site.data.alerts.end}}
65+
6266
Example URLs for [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), or [`EXPORT`]({% link {{ page.version.version }}/export.md %}) given a bucket or container name of `acme-co` and an `employees` subdirectory:
6367

6468
Location | Example

‎src/current/v25.2/backup-validation.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,10 @@ You can validate a backup of a [cluster]({% link {{ page.version.version }}/back
1515

1616
The options that give the most validation coverage will increase the runtime of the check. That is, `verify_backup_table_data` will take a longer time to validate a backup compared to `check_files` or `schema_only` alone. Despite that, each of these validation options provide a quicker way to validate a backup over running a "regular" restore.
1717

18+
{{site.data.alerts.callout_success}}
19+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
20+
{{site.data.alerts.end}}
21+
1822
## Recommendations
1923

2024
Cockroach Labs recommends implementing the following validation plan to test your backups:

‎src/current/v25.2/backup.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,10 @@ To view the contents of an backup created with the `BACKUP` statement, use [`SHO
4444
- Modifying backup files in the storage location could invalidate a backup, and therefore, prevent a restore. In v22.1 and later, **we recommend enabling [object locking]({% link {{ page.version.version }}/use-cloud-storage.md %}#immutable-storage) in your cloud storage bucket.**
4545
- While Cockroach Labs actively tests Amazon S3, Google Cloud Storage, and Azure Storage, we **do not** test [S3-compatible services]({% link {{ page.version.version }}/use-cloud-storage.md %}) (e.g., [MinIO](https://min.io/), [Red Hat Ceph](https://docs.ceph.com/en/pacific/radosgw/s3/)).
4646

47+
{{site.data.alerts.callout_success}}
48+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
49+
{{site.data.alerts.end}}
50+
4751
## Required privileges
4852

4953
{% include {{ page.version.version }}/backups/updated-backup-privileges.md %}

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

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

‎src/current/v25.2/cloud-storage-authentication.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,10 @@ Cockroach Labs supports different levels of authentication to cloud storage. Whe
1111
We recommend using IAM roles for users to authenticate to cloud storage resources. For more detail, see the assume role and workload identity sections for [Amazon S3]({% link {{ page.version.version }}/cloud-storage-authentication.md %}#set-up-amazon-s3-assume-role) and [Google Cloud Storage](cloud-storage-authentication.html?filters=gcs#set-up-google-cloud-storage-assume-role).
1212
{{site.data.alerts.end}}
1313

14+
{{site.data.alerts.callout_success}}
15+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
16+
{{site.data.alerts.end}}
17+
1418
<div class="filters clearfix">
1519
<button class="filter-button" data-scope="s3">Amazon S3</button>
1620
<button class="filter-button" data-scope="gcs">Google Cloud Storage</button>

‎src/current/v25.2/use-cloud-storage.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,10 @@ You can disable the use of implicit credentials when accessing external cloud st
5959

6060
### Example file URLs
6161

62+
{{site.data.alerts.callout_success}}
63+
{% include {{ page.version.version }}/backups/external-storage-check-tip.md %}
64+
{{site.data.alerts.end}}
65+
6266
Example URLs for [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), or [`EXPORT`]({% link {{ page.version.version }}/export.md %}) given a bucket or container name of `acme-co` and an `employees` subdirectory:
6367

6468
Location | Example

0 commit comments

Comments
 (0)