Feedback: cockroach start

[hand-crdb]

Steven Hand (hand-crdb) commented:

Page: https://cockroachlabs.com/docs/v23.1/cockroach-start.html

What is the reason for your feedback?

[ ] Missing the information I need

[ ] Too complicated

[ ] Out of date

[ ] Something is broken

[X] Other

Additional details

This sentence describing the --external-io-dir flag is:

• confusing and is possibly incorrect
• does not provide enough guidance in real-world situations

To set the --external-io-dir flag to the locations you want to use without needing to restart nodes, create symlinks to the desired locations from within the extern directory.

First, it is confusing and possibly incorrect because it is describing how to not set the --external-io-dir flag. Yet the sentence begins with "To set the --external-io-dir flag...".

An alternate way of saying this might be something like:

To achieve an effect similar to setting the --external-io-dir flag, yet without needing to restart nodes, create symlinks to the desired locations from within the extern directory.

Second, this sentence does not provide enough guidance in real-world situations because the approach recommended only works if the customer knows ahead of time what names CockroachDB will use for the items it creates in the extern directory. Please consult with the development team to see if there is a way to address this.

For example, one approach might be to make the extern directory itself be a symlink, instead of creating symlinks within the extern directory. To do this, a customer would delete the extern directory and replace it with a symlink named extern. However, the development team may object to this approach because it requires manually making changes within a node's store.

Lastly, I want to mention that the approaches mentioned above are not mutually exclusive. It may be possible to both create symlinks within the extern directory, and to make the extern directory itself be a symlink. This may afford more options for customers, depending on how fine a granularity they may need for specifying file destinations.

THANK YOU

Jira Issue: DOC-8685