CockroachDB Demo Locations
Tags: database, sql, cockroachdb
Published: 2019-12-09 16:20:01

The [`cockroach demo`](https://www.cockroachlabs.com/blog/get-started-geo-partitioning-data-with-our-command-line-cockroachdb-demo/) command is my current favourite dev tool. It's instant access to an N-node CockroachDB cluster, allowing you to get up and running with an enterprise cluster straight from your dev environment, reducing feedback loops massively by giving you all the features you need to create with confidence.

If you start a cluster with `cockroach demo`, and don't provide any arguments for `--demo-locality`, you'll get the default values that are provided by the [demo code](https://github.com/cockroachdb/cockroach/blob/master/pkg/cli/demo.go#L73).

| --nodes | Regions |
| :------ | :------ |
| 1 | us-east1 x1 |
| 2 | us-east1 x2 |
| 3 | us-east1 x3 |
| 4 | us-east1 x3 + us-west1 x1 |
| 5 | us-east1 x3 + us-west1 x2 |
| 6 | us-east1 x3 + us-west1 x3 |
| 7 | us-east1 x3 + us-west1 x3 + europe-west1 x1 |
| 8 | us-east1 x3 + us-west1 x3 + europe-west1 x2 |
| 9 | us-east1 x3 + us-west1 x3 + europe-west1 x3 |
<br />
The increase is cyclical, with every additional node for the first 3 additional nodes, adding to the us-east1 region and so on.

Currently, only the us-east1, us-west1, and europe-west1 regions have [locations](https://github.com/cockroachdb/cockroach/blob/master/pkg/cli/demo.go#L107) configured, so if you'd like spin up nodes in other regions and have them represented in the cluster map, it's a very simple two-step process:

##### Step 1 - create your cluster with custom regions

The following spins up a 10-node cluster across 3 regions; us-central1 (4 AZs), asia-northeast1 (3 AZs), and europe-west1 (3 AZs): 

```
cockroach demo \
--empty \
--nodes 10 \
--demo-locality=region=us-central1,az=a:region=us-central1,az=b:region=us-central1,az=c:region=us-central1,az=f:region=asia-northeast1,az=a:region=asia-northeast1,az=b:region=asia-northeast1,az=c:region=europe-west1,az=a:region=europe-west1,az=b:region=europe-west1,az=c
```

If you open the cluster map in the web UI now, you'll see a message that explains that not all of your regions have been assigned locations. In the knowledge that only a handful of regions come pre-loaded with location information, we can infer that the asia-northeast1 region needs to be given a location.

This can be confirmed by running the following SQL in your console session:

``` sql
select * from system.locations;
```

| localityKey | localityValue | latitude | longitude |
| :---------- | :------------ | :------- | :-------- |
|  region | europe-west1 | 50.448160000000000 | 3.818860000000000 |
|  region | us-central1 | 42.032974000000000 | -93.581543000000000 |
|  region | us-east1 | 33.836082000000000 | -81.163727000000000 |
|  region | us-east4 | 37.478397000000000 | -76.453077000000000 |
|  region | us-west1 | 43.804133000000000 | -120.554201000000000 |

Helpfully, the cluster map provides a [link](https://www.cockroachlabs.com/docs/v19.2/enable-node-map.html#location-coordinates-for-reference) to docs that will help you assign locations to your regions. You can follow the docs, or continue to read to find out how this can be done.

##### Step 2 - assign localities to custom regions

Insert location information for the asia-northeast1 region by running the following SQL in your console session:

``` sql
INSERT into system.locations VALUES ('region', 'asia-northeast1', 35.689487, 139.691706);
```

If you refresh your node map now, you'll see a 9-node cluster, with 3 regions configured in the locations you've configured.