> ## Documentation Index > Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # cockroach gen export const InternalLink = ({version, path = "", children, ...props}) => { let detectedVersion = version || "stable"; if (typeof window !== 'undefined' && !version) { const match = window.location.pathname.match(/\/docs\/([^/]+)/); if (match) { detectedVersion = match[1]; } } const normalizedPath = path.startsWith("/") ? path.slice(1) : path; return {children} ; }; The `cockroach gen` command can generate command-line interface (CLI) utilities ([`man` pages](https://wikipedia.org/wiki/Man_page) 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 ` 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. Decommissioned nodes are excluded from the config file. | ## Synopsis Generate man pages: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen man ``` Generate bash autocompletion script: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen autocomplete ``` Generate example SQL data: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen example-data intro | cockroach sql ``` ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen example-data startrek | cockroach sql ``` Generate an HAProxy config file for a running cluster: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen haproxy ``` View help: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen --help ``` ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen man --help ``` ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen autocomplete --help ``` ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen example-data --help ``` ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen haproxy --help ``` ## Flags The `gen` subcommands supports the following [general-use](#general), [logging](#logging), and [client connection](#client-connection) 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](#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\_HOST` **Default:**`localhost:26257` | | `--port` `-p` | The server port to connect to. Note: The port number can also be specified via `--host`. **Env Variable:**`COCKROACH\_PORT` **Default:**`26257` | | `--insecure` | Use an insecure connection. **Env Variable:**`COCKROACH\_INSECURE` **Default:**`false` | | `--certs-dir` | The path to the certificate directory containing the CA and client certificates and client key. **Env Variable:**`COCKROACH\_CERTS\_DIR` **Default:**`${HOME}/.cockroach-certs/` | | `--url` | A connection URL to use instead of the other arguments. **Env Variable:**`COCKROACH\_URL` **Default:** 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](#generate-an-haproxy-config-file) example for more details. | ### Logging By default, this command logs messages to `stderr`. This includes events with `WARNING` severity and higher. If you need to troubleshoot this command's behavior, you can customize its logging behavior. ### Client Connection #### `haproxy` | Flag | Description | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--cluster-name` | The cluster name to use to verify the cluster's identity. If the cluster has a cluster name, you must include this flag. For more information, see `cockroach start`. | | `--disable-cluster-name-verification` | Disables the cluster name check for this command. This flag must be paired with `--cluster-name`. For more information, see `cockroach start`. | ## Examples ### Generate `man` pages Generate man pages: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen man ``` Move the man pages to the man directory: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ sudo mv man/man1/* /usr/share/man/man1 ``` Access man pages: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ man cockroach ``` ### Generate a `bash` autocompletion script Generate bash autocompletion script: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen autocomplete ``` Add the script to your `.bashrc` and `.bash_profle`: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ printf "\n\n#cockroach bash autocomplete\nsource '> ~/.bashrc ``` ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ printf "\n\n#cockroach bash autocomplete\nsource '> ~/.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 ` 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`. 1. Start up a demo cluster: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach demo ``` 2. Pipe the output from `cockroach gen` to the URL to the demo cluster: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach gen example-data startrek | cockroach sql --url='postgres://demo:demo11762@127.0.0.1:26257?sslmode=require' ``` ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} CREATE DATABASE SET DROP TABLE DROP TABLE CREATE TABLE INSERT 1 ... CREATE TABLE INSERT 1 ... ``` 3. Open a SQL shell to view it: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach sql --url='postgres://demo:demo11762@127.0.0.1:26257?sslmode=require' ``` ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} SHOW TABLES FROM startrek; ``` ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} schema_name | table_name | type | estimated_row_count --------------+------------+-------+---------------------- public | episodes | table | 79 public | quotes | table | 200 (2 rows) ``` 4. Generate an example `intro` database, which contains 1 table, `mytable`, with a hidden message: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach gen example-data intro | cockroach sql --url='postgres://demo:demo11762@127.0.0.1:26257?sslmode=require' ``` ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} CREATE DATABASE SET DROP TABLE CREATE TABLE INSERT 1 INSERT 1 INSERT 1 INSERT 1 ... ``` 5. Launch the SQL client to view it: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} cockroach sql --url='postgres://demo:demo11762@127.0.0.1:26257?sslmode=require' ``` 6. Show the tables in the `intro` database: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} > SHOW TABLES FROM intro; ``` ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} schema_name | table_name | type | estimated_row_count --------------+------------+-------+---------------------- public | mytable | table | 42 (1 row) ``` 7. Select the message from the table: ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} > SELECT * FROM intro.mytable WHERE (l % 2) = 0; ``` ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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](http://www.haproxy.org/) 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen haproxy \ --certs-dir="localities", use the `--localities` flag, specifying the explicit locality tier(s) or a regular expression to match against: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen haproxy \ --certs-dir= To generate an HAProxy config file for an entire insecure cluster, run the `cockroach gen haproxy` command, specifying the address of any instance running a CockroachDB node: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen haproxy \ --insecure \ --host=
"localities", use the `--localities` flag, specifying the explicit locality tier(s) or a regular expression to match against: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} $ cockroach gen haproxy \ --insecure \ --host=
By default, the generated configuration file is called `haproxy.cfg` and looks as follows, with the `server` addresses pre-populated correctly: ```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} global maxconn 4096 defaults mode tcp # Timeout values should be configured for your specific use. # See: https://cbonte.github.io/haproxy-dconv/1.8/configuration.html#4-timeout%20connect timeout connect 10s timeout client 1m timeout server 1m # TCP keep-alive on client side. Server already enables them. option clitcpka listen psql bind :26257 mode tcp balance roundrobin option httpchk GET /health?ready=1 server cockroach1 :26257 check port 8080 server cockroach2 :26257 check port 8080 server cockroach3 :26257 check port 8080 ``` The file is preset with the minimal [configurations](http://cbonte.github.io/haproxy-dconv/1.7/configuration) needed to work with your running cluster: | Field | Description | | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `timeout connect` `timeout client` `timeout server` | Timeout values that should be suitable for most deployments. | | `bind` | The port that HAProxy listens on. This is the port clients will connect to and thus needs to be allowed by your network configuration. This tutorial assumes HAProxy is running on a separate machine from CockroachDB nodes. If you run HAProxy on the same machine as a node (not recommended), you'll need to change this port, as `26257` is likely already being used by the CockroachDB node. | | `balance` | The balancing algorithm. This is set to `roundrobin` to ensure that connections get rotated amongst nodes (connection 1 on node 1, connection 2 on node 2, etc.). Check the [HAProxy Configuration Manual](http://cbonte.github.io/haproxy-dconv/1.7/configuration#4-balance) for details about this and other balancing algorithms. | | `option httpchk` | The HTTP endpoint that HAProxy uses to check node health. `/health?ready=1` ensures that HAProxy doesn't direct traffic to nodes that are live but not ready to receive requests. | | `server` | For each included node, this field specifies the address the node advertises to other nodes in the cluster, i.e., the addressed pass in the `--advertise-addr` flag on node startup. Make sure hostnames are resolvable and IP addresses are routable from HAProxy. | For full details on these and other configuration settings, see the [HAProxy Configuration Manual](http://cbonte.github.io/haproxy-dconv/1.7/configuration). ## See also * `cockroach` Commands Overview * Deploy CockroachDB On-Premises (using HAProxy for load balancing)