> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using GeoServer with CockroachDB

This page has instructions for configuring [GeoServer](http://geoserver.org/) to use CockroachDB as the underlying database.

The instructions here reuse parts of the data set described in the [Spatial Data tutorial](https://docs.cockroachlabs.com/docs/v24.3/spatial-tutorial), specifically the `tutorial.roads` table, which contains the [U.S. National Atlas data set](https://www.sciencebase.gov/catalog/file/get/581d052be4b08da350d524ce?f=__disk__60%2F6b%2F4e%2F606b4e564884da8cca57ffeb229cd817006616e0\&transform=1\&allowOpen=true).

Many of the instructions on this page come from the following GeoServer documentation pages:

* [Using the web administration interface](https://docs.geoserver.org/stable/en/user/gettingstarted/web-admin-quickstart)
* [Publishing a PostGIS table](https://docs.geoserver.org/stable/en/user/gettingstarted/postgis-quickstart).

## Before you begin

You must have the following set up before proceeding with this tutorial:

* CockroachDB [installed on the local machine](https://docs.cockroachlabs.com/docs/v24.3/install-cockroachdb-mac.md)
* GeoServer [installed on the local machine](https://docs.geoserver.org/stable/en/user/installation#installation).

> [!TIP]
>
> Mac users who use [Homebrew](https://brew.sh/) can install GeoServer by typing `brew install geoserver`.

These instructions assume you are running on a UNIX-like system.

## Step 1. Start CockroachDB and connect to your cluster

Start a CockroachDB cluster by following the instructions in [Start a Local Cluster](https://docs.cockroachlabs.com/docs/v24.3/start-a-local-cluster.md).

## Step 2. Load spatial data

Connect to the running cluster from the [SQL client](https://docs.cockroachlabs.com/docs/v24.3/cockroach-sql.md) and enter the statements below.

1. [Create](https://docs.cockroachlabs.com/docs/v24.3/create-database.md) the `tutorial` database:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   CREATE DATABASE tutorial;
   ```
2. Switch to the `tutorial` database:

   ```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   USE tutorial;
   ```
3. In a separate terminal, download the spatial data set:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   curl -o bookstores-and-roads.sql https://spatial-tutorial.s3.us-east-2.amazonaws.com/bookstores-and-roads-20210125.sql
   ```
4. Pipe the data set directly into [cockroach sql](https://docs.cockroachlabs.com/docs/v24.3/cockroach-sql.md), specifying the [connection string](https://docs.cockroachlabs.com/docs/v24.3/connection-parameters.md#connect-using-a-url) of your local cluster:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   cockroach sql --url {"CONNECTION STRING"} < bookstores-and-roads.sql
   ```

   The SQL execution will take some time to complete.

## Step 3. Turn on CockroachDB's experimental box comparison operators

CockroachDB's support for GeoServer is still in development. To use CockroachDB with GeoServer, you will need to enable the use of certain experimental box2d comparison operators by changing the following [cluster setting](https://docs.cockroachlabs.com/docs/v24.3/cluster-settings.md):

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
SET CLUSTER SETTING sql.spatial.experimental_box2d_comparison_operators.enabled = ON;
```

The reasons the box2d comparison operators are experimental in CockroachDB are as follows:

* PostGIS uses the `&&`, `~`, and `@` operators to do bounding box comparisons. These comparisons can always be index-accelerated by PostgreSQL since it uses [R-tree based indexing](https://wikipedia.org/wiki/R-tree) to generate its coverings.
* CockroachDB [uses a different indexing strategy based on space-filling curves](https://docs.cockroachlabs.com/docs/v24.3/spatial-indexes.md) since this is necessary for [scaling horizontally](https://docs.cockroachlabs.com/docs/v24.3/frequently-asked-questions.md).
  * This means that the coverings generated by CockroachDB's `&&`, `~`, and `@` operators for index-accelerated lookups are not the same as the bounding box coverings generated by PostGIS.
  * In practice, CockroachDB may return a smaller set of results for the same query, as the space-filling curve covering is often more exact than a bounding box covering, and will exclude from the result set any geometries that have an intersecting bounding box but where no part of the geometry hits the actual bounding box.
  * Note that the behavior described above only applies to index-accelerated lookups.

## Step 4. Start GeoServer

The easiest place to create the GeoServer data directory is in your user's home directory.

1. In the UNIX shell, run the following command:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   mkdir -p $HOME/geoserver
   ```
2. Start GeoServer by running the following command:

   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   geoserver $HOME/geoserver
   ```

You should see some log output that looks like the following:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
2021-06-23 11:44:22.617:INFO::main: Logging initialized @721ms to org.eclipse.jetty.util.log.StdErrLog
2021-06-23 11:44:22.944:INFO:oejs.Server:main: jetty-9.4.36.v20210114; built: 2021-01-14T16:44:28.689Z; git: 238ec6997c7806b055319a6d11f8ae7564adc0de; jvm 1.8.0_282-b08
2021-06-23 11:44:22.969:INFO:oejdp.ScanningAppProvider:main: Deployment monitor [file:///usr/local/Cellar/geoserver/2.19.1/libexec/webapps/] at interval 1
2021-06-23 11:44:23.732:INFO:oejw.StandardDescriptorProcessor:main: NO JSP Support for /geoserver, did not find org.eclipse.jetty.jsp.JettyJspServlet
2021-06-23 11:44:24.687:INFO:oejs.session:main: DefaultSessionIdManager workerName=node0
2021-06-23 11:44:24.687:INFO:oejs.session:main: No SessionScavenger set, using defaults
...
```

## Step 5. Log in to GeoServer

In this and the following steps we will set up GeoServer so it can access the spatial data we loaded in [Step 2](#step-2-load-spatial-data).

Open your web browser and navigate to your [locally running GeoServer instance](http://localhost:8080/geoserver/web). Log in using the default credentials: username `admin`, password `geoserver`.

## Step 6. Set up a GeoServer Workspace

In the left-hand navigation menu, click **Data > Workspaces**. The **Workspaces** page will load. Click the **Add new workspace** button.

On the **New Workspace** page, enter the following information:

* In the **Name** field, enter the text "spatial-tutorial".
* In the **Namespace URI** field, enter the URL for the spatial tutorial where this data set is used: `/docs/v24.3/spatial-tutorial.html`.

Press the **Save** button.

You will be redirected to the **Workspaces** page, and you should see a workspace called **spatial-tutorial** in the list.

## Step 7. Configure GeoServer to use CockroachDB

In the left-hand navigation menu, click **Data > Stores**. The **Stores** page will load. Click the **Add new Store** button.

You will be taken to the **New data source** page. Under the list of **Vector Data Sources**, click **PostGIS**.

This opens the **New Vector Data Source** page, where you need to enter the following information:

1. Under **Basic Store Info**, fill in the **Data Source Name** field with the text: `CockroachDB`
2. Under **Connection Parameters**, edit **port** to the default CockroachDB port: `26257`
3. Edit the **database** field to add the text: `tutorial`
4. Fill in the **user** field with the text: `root`
5. Delete the contents of the **passwd** field, if any

Click **Save**, and you will be redirected to the **New Layer** page, with the following unpublished layers:

* bookstore\_routes
* bookstores
* roads

Click the **Publish** button to the right of the `roads` layer.

This will bring you to the **Edit Layer** page, where you need to enter the following information:

1. In the **Bounding Boxes** section, for the **Native Bounding Box** settings, click the **Compute from data** button, which will fill in the form fields.
2. Also in the **Bounding Boxes** section, for the **Lat/Lon Bounding Box** setting, click the **Compute from native bounds** button, which will fill in the form fields.

Click **Save**, and you will be redirected to the **Layers** page.

## Step 8. View the `roads` layer

In the left-hand navigation menu, click **Data > Layer Preview**.

You will be redirected to the **Layer Preview** page.

In the row for the `roads` layer, click the **OpenLayers** button under the **Common Formats** column.

Your browser should open a new tab with the title **OpenLayers map preview**. It should show a map view that looks like the following:

![GeoServer U.S. National Atlas preview](https://mintcdn.com/cockroachlabs/bBD0UEapbn6fk8Rb/images/common/geospatial/geoserver-us-atlas-00.png?fit=max\&auto=format\&n=bBD0UEapbn6fk8Rb\&q=85\&s=6b88ef93a57b02284f2becb3fc4f4f7f)

## See also

* [Install CockroachDB](https://docs.cockroachlabs.com/docs/v24.3/install-cockroachdb-mac.md)
* [Spatial Data Overview](https://docs.cockroachlabs.com/docs/v24.3/spatial-data-overview.md)
* [Spatial Indexes](https://docs.cockroachlabs.com/docs/v24.3/spatial-indexes.md)
* [Spatial & GIS Glossary of Terms](https://docs.cockroachlabs.com/docs/v24.3/architecture/glossary.md)
* [Export Spatial Data](https://docs.cockroachlabs.com/docs/v24.3/export-spatial-data)
* [Migrate from Shapefiles](https://docs.cockroachlabs.com/docs/v24.3/migrate-from-shapefiles.md)
* [Migrate from GeoJSON](https://docs.cockroachlabs.com/docs/v24.3/migrate-from-geojson.md)
* [Migrate from GeoPackage](https://docs.cockroachlabs.com/docs/v24.3/migrate-from-geopackage.md)
* [Migrate from OpenStreetMap](https://docs.cockroachlabs.com/docs/v24.3/migrate-from-openstreetmap.md)
* [Spatial Functions](https://docs.cockroachlabs.com/docs/v24.3/functions-and-operators.md#spatial-functions)
* [POINT](https://docs.cockroachlabs.com/docs/v24.3/point.md)
* [LINESTRING](https://docs.cockroachlabs.com/docs/v24.3/linestring.md)
* [POLYGON](https://docs.cockroachlabs.com/docs/v24.3/polygon.md)
* [MULTIPOINT](https://docs.cockroachlabs.com/docs/v24.3/multipoint.md)
* [MULTILINESTRING](https://docs.cockroachlabs.com/docs/v24.3/multilinestring.md)
* [MULTIPOLYGON](https://docs.cockroachlabs.com/docs/v24.3/multipolygon.md)
* [GEOMETRYCOLLECTION](https://docs.cockroachlabs.com/docs/v24.3/geometrycollection.md)
* [Well Known Text](https://docs.cockroachlabs.com/docs/v24.3/well-known-text.md)
* [Well Known Binary](https://docs.cockroachlabs.com/docs/v24.3/well-known-binary.md)
* [GeoJSON](https://docs.cockroachlabs.com/docs/v24.3/geojson.md)
* [SRID 4326 - Longitude and Latitude](https://docs.cockroachlabs.com/docs/v24.3/srid-4326.md)
* [`ST_Contains`](https://docs.cockroachlabs.com/docs/v24.3/st_contains)
* [`ST_ConvexHull`](https://docs.cockroachlabs.com/docs/v24.3/st_convexhull)
* [`ST_CoveredBy`](https://docs.cockroachlabs.com/docs/v24.3/st_coveredby)
* [`ST_Covers`](https://docs.cockroachlabs.com/docs/v24.3/st_covers)
* [`ST_Disjoint`](https://docs.cockroachlabs.com/docs/v24.3/st_disjoint)
* [`ST_Equals`](https://docs.cockroachlabs.com/docs/v24.3/st_equals)
* [`ST_Intersects`](https://docs.cockroachlabs.com/docs/v24.3/st_intersects)
* [`ST_Overlaps`](https://docs.cockroachlabs.com/docs/v24.3/st_overlaps)
* [`ST_Touches`](https://docs.cockroachlabs.com/docs/v24.3/st_touches)
* [`ST_Union`](https://docs.cockroachlabs.com/docs/v24.3/st_union)
* [`ST_Within`](https://docs.cockroachlabs.com/docs/v24.3/st_within)
* [Troubleshooting Overview](https://docs.cockroachlabs.com/docs/v24.3/troubleshooting-overview.md)
* [Support Resources](https://docs.cockroachlabs.com/docs/v24.3/support-resources.md)