The cockroach gen command can generate command-line interface (CLI) utilities (man pages and a bash autocompletion script), example SQL data suitable to populate test databases, and an HAProxy configuration file for load balancing a running cluster.
Subcommands
| Subcommand | Usage |
|---|---|
man |
Generate man pages for CockroachDB. |
autocomplete |
Generate bash or zsh autocompletion script for CockroachDB.Default: bash |
example-data |
Generate example SQL datasets. You can also use the cockroach workload command to generate these sample datasets in a persistent cluster and the cockroach demo <dataset> command to generate these datasets in a temporary, in-memory cluster. |
haproxy |
Generate an HAProxy config file for a running CockroachDB cluster. The node addresses included in the config are those advertised by the nodes. Make sure hostnames are resolvable and IP addresses are routable from HAProxy. |
Synopsis
Generate man pages:
$ cockroach gen man
Generate bash autocompletion script:
$ cockroach gen autocomplete
Generate example SQL data:
$ cockroach gen example-data intro | cockroach sql
$ cockroach gen example-data startrek | cockroach sql
Generate an HAProxy config file for a running cluster:
$ cockroach gen haproxy
View help:
$ cockroach gen --help
$ cockroach gen man --help
$ cockroach gen autocomplete --help
$ cockroach gen example-data --help
$ cockroach gen haproxy --help
Flags
The gen subcommands supports the following general-use and logging flags.
General
man
| Flag | Description |
|---|---|
--path |
The path where man pages will be generated. Default: man/man1 under the current directory |
autocomplete
| Flag | Description |
|---|---|
--out |
The path where the autocomplete file will be generated. Default: cockroach.bash in the current directory |
example-data
No flags are supported. See the Generate Example Data example for guidance.
haproxy
| Flag | Description |
|---|---|
--host |
The server host and port number to connect to. This can be the address of any node in the cluster. Env Variable: COCKROACH_HOSTDefault: localhost:26257 |
--port-p |
The server port to connect to. Note: The port number can also be specified via --host. Env Variable: COCKROACH_PORTDefault: 26257 |
--insecure |
Use an insecure connection. Env Variable: COCKROACH_INSECUREDefault: false |
--certs-dir |
The path to the certificate directory containing the CA and client certificates and client key. Env Variable: COCKROACH_CERTS_DIRDefault: ${HOME}/.cockroach-certs/ |
--url |
A connection URL to use instead of the other arguments. Env Variable: COCKROACH_URLDefault: no URL |
--out |
The path where the haproxy.cfg file will be generated. If an haproxy.cfg file already exists in the directory, it will be overwritten.Default: haproxy.cfg in the current directory |
--locality |
If nodes were started with locality details, you can use the --locality flag here to filter the nodes included in the HAProxy config file, specifying the explicit locality tier(s) or a regular expression to match against. This is useful in cases where you want specific instances of HAProxy to route to specific nodes. See the Generate an HAProxy configuration file example for more details. |
Logging
By default, the gen command logs errors to stderr.
If you need to troubleshoot this command's behavior, you can change its logging behavior.
Examples
Generate man pages
Generate man pages:
$ cockroach gen man
Move the man pages to the man directory:
$ sudo mv man/man1/* /usr/share/man/man1
Access man pages:
$ man cockroach
Generate a bash autocompletion script
Generate bash autocompletion script:
$ cockroach gen autocomplete
Add the script to your .bashrc and .bash_profle:
$ printf "\n\n#cockroach bash autocomplete\nsource '<path to>cockroach.bash'" >> ~/.bashrc
$ printf "\n\n#cockroach bash autocomplete\nsource '<path to>cockroach.bash'" >> ~/.bash_profile
You can now use tab to autocomplete cockroach commands.
Generate example data
You can also use the cockroach workload command to generate these sample datasets in a persistent cluster and the cockroach demo <dataset> command to generate these datasets in a temporary, in-memory cluster.
To test out CockroachDB, you can generate an example startrek database, which contains 2 tables, episodes and quotes.
$ cockroach gen example-data startrek | cockroach sql --insecure
CREATE DATABASE
SET
DROP TABLE
DROP TABLE
CREATE TABLE
INSERT 79
CREATE TABLE
INSERT 200
Launch the built-in SQL client to view it:
$ cockroach sql --insecure
> SHOW TABLES FROM startrek;
+------------+
| table_name |
+------------+
| episodes |
| quotes |
+------------+
(2 rows)
You can also generate an example intro database, which contains 1 table, mytable, with a hidden message:
$ cockroach gen example-data intro | cockroach sql --insecure
CREATE DATABASE
SET
DROP TABLE
CREATE TABLE
INSERT 1
INSERT 1
INSERT 1
INSERT 1
...
# Launch the built-in SQL client to view it:
$ cockroach sql --insecure
> SHOW TABLES FROM intro;
+-------------+
| table_name |
+-------------+
| mytable |
+-------------+
(1 row)
> SELECT * FROM intro.mytable WHERE (l % 2) = 0;
+----+------------------------------------------------------+
| l | v |
+----+------------------------------------------------------+
| 0 | !__aaawwmqmqmwwwaas,,_ .__aaawwwmqmqmwwaaa,, |
| 2 | !"VT?!"""^~~^"""??T$Wmqaa,_auqmWBT?!"""^~~^^""??YV^ |
| 4 | ! "?##mW##?"- |
| 6 | ! C O N G R A T S _am#Z??A#ma, Y |
| 8 | ! _ummY" "9#ma, A |
| 10 | ! vm#Z( )Xmms Y |
| 12 | ! .j####mmm#####mm#m##6. |
| 14 | ! W O W ! jmm###mm######m#mmm##6 |
| 16 | ! ]#me*Xm#m#mm##m#m##SX##c |
| 18 | ! dm#||+*$##m#mm#m#Svvn##m |
| 20 | ! :mmE=|+||S##m##m#1nvnnX##; A |
| 22 | ! :m#h+|+++=Xmm#m#1nvnnvdmm; M |
| 24 | ! Y $#m>+|+|||##m#1nvnnnnmm# A |
| 26 | ! O ]##z+|+|+|3#mEnnnnvnd##f Z |
| 28 | ! U D 4##c|+|+|]m#kvnvnno##P E |
| 30 | ! I 4#ma+|++]mmhvnnvq##P` ! |
| 32 | ! D I ?$#q%+|dmmmvnnm##! |
| 34 | ! T -4##wu#mm#pw##7' |
| 36 | ! -?$##m####Y' |
| 38 | ! !! "Y##Y"- |
| 40 | ! |
+----+------------------------------------------------------+
(21 rows)
Generate an HAProxy config file
HAProxy is one of the most popular open-source TCP load balancers, and CockroachDB includes a built-in command for generating a configuration file that is preset to work with your running cluster.
To generate an HAProxy config file for an entire secure cluster, run the cockroach gen haproxy command, specifying the location of certificate directory and the address of any instance running a CockroachDB node:
$ cockroach gen haproxy \
--certs-dir=<path to certs directory> \
--host=<address of any node in the cluster>
To limit the HAProxy config file to nodes matching specific "localities", use the --localities flag, specifying the explicit locality tier(s) or a regular expression to match against:
$ cockroach gen haproxy \
--certs-dir=<path to certs directory> \
--host=<address of any node in the cluster>
--locality=region=us.*