Update spatial install/import/libs info

Fixes #8400, #8649. Addresses #8743, #8780. Summary of changes: - Update 'Install CockroachDB Spatial' and 'Working with Spatial Data' to point to the latest (pre-GA) release. - Update 'Working with Spatial Data' to use `IMPORT PGDUMP` to bring in the tornadoes data set (auxiliary script & `cockroach sql` no longer required). - Add docs to `cockroach start` for the `--spatial-libs` flag, and link to them from 'Install CockroachDB Spatial'. - Update an old set of release notes to remove the confusing use of the term "static" re: the spatial libraries, which are dynamically linked. - Add some more cross-linkage between 'Working with Spatial Data', 'Install CockroachDB Spatial', and the other recently added spatial pages.
cockroachdb · Nov 4, 2020 · 42711d2 · 42711d2
1 parent 1740d89
commit 42711d2
Show file tree

Hide file tree

Showing 4 changed files with 96 additions and 62 deletions.
diff --git a/releases/v20.2.0-alpha.3.md b/releases/v20.2.0-alpha.3.md
@@ -49,7 +49,7 @@ $ docker pull cockroachdb/cockroach-unstable:v20.2.0-alpha.3
 - [`cockroach node recommission`](../v20.2/remove-nodes.html#recommission-nodes) has new semantics. Previously it was able to recommission any decommissioning node, regardless of how long ago its was decommissioned, or removed from the cluster. Now `cockroach node recommission` serves to only cancel an accidental inflight decommissioning process that wasn't finalized. [#50329][#50329]
 - CPU profiles are now taken as part of the [`cockroach debug zip`](../v20.2/cockroach-debug-zip.html) command. [#50625][#50625]
 - CPU profiles taken from CockroachDB servers now contain more profiler labels related to ongoing SQL processing. [#50625][#50625]
-- The [CockroachDB tarballs](#downloads) now include the `libgeos` and `libgeos_c` static libraries, which are required to be copied to `/usr/local/lib/cockroach` for UNIX/MacOS systems to [perform certain geospatial operations](../v20.2/spatial-data.html). The Windows location will be finalized at a later date. This location is configurable with the `--geo-libs` flag to `cockroach start`. [#51108][#51108]
+- The [CockroachDB tarballs](#downloads) now include the `libgeos` and `libgeos_c` libraries, which are required to be copied to `/usr/local/lib/cockroach` for UNIX/MacOS systems to [perform certain geospatial operations](../v20.2/spatial-data.html). The Windows location will be finalized at a later date. This location is configurable with the `--geo-libs` flag to `cockroach start`. [#51108][#51108]
 - The Docker container that ships with CockroachDB now includes the [GEOS](../v20.2/spatial-glossary.html#geos) library needed for geospatial functionality in `/usr/local/lib/cockroach` (which is the default location where the `cockroach` binary looks for the GEOS libraries). [#51392][#51392]
 - [Timestamp](../v20.2/timestamp.html) functions are now supported by [`IMPORT INTO`](../v20.2/import-into.html). [#51390][#51390]
 - [`IMPORT INTO`](../v20.2/import-into.html) now supports `unique_rowid()` as a default expression. [#50922][#50922]

diff --git a/v20.2/cockroach-start.md b/v20.2/cockroach-start.md
@@ -65,6 +65,7 @@ Flag | Description
 `--max-sql-memory` | The maximum in-memory storage capacity available to store temporary data for SQL queries, including prepared queries and intermediate data rows during query execution. This can be a percentage (notated as a decimal or with `%`) or any bytes-based unit, for example:<br><br>`--max-sql-memory=.25`<br>`--max-sql-memory=25%`<br>`--max-sql-memory=10000000000 ----> 1000000000 bytes`<br>`--max-sql-memory=1GB ----> 1000000000 bytes`<br>`--max-sql-memory=1GiB ----> 1073741824 bytes`<br><br>The temporary files are located in the path specified by the `--temp-dir` flag, or in the subdirectory of the first store (see `--store`) by default.<br><br><strong>Note:</strong> If you use the `%` notation, you might need to escape the `%` sign, for instance, while configuring CockroachDB through `systemd` service files. For this reason, it's recommended to use the decimal notation instead.<br><br>**Default:** `25%` <br><br>The default SQL memory size is suitable for production deployments but can be raised to increase the number of simultaneous client connections the node allows as well as the node's capacity for in-memory processing of rows when using `ORDER BY`, `GROUP BY`, `DISTINCT`, joins, and window functions. For local development clusters with memory-intensive workloads, reduce this value to, for example, `128MiB` to prevent out of memory errors.
 `--pid-file` | The file to which the node's process ID will be written as soon as the node is ready to accept connections. When `--background` is used, this happens before the process detaches from the terminal. When this flag is not set, the process ID is not written to file.
 `--store`<br>`-s` | The file path to a storage device and, optionally, store attributes and maximum size. When using multiple storage devices for a node, this flag must be specified separately for each device, for example: <br><br>`--store=/mnt/ssd01 --store=/mnt/ssd02` <br><br>For more details, see [Store](#store) below.
+<a name="flags-spatial-libs"></a>`--spatial-libs` | The location on disk where CockroachDB looks for spatial libraries. <br/><br/>**Default:** `/usr/local/lib/cockroach`<br/><br/>Example: `--spatial-libs=/path/to/libs`
 `--temp-dir` <a name="temp-dir"></a> | The path of the node's temporary store directory. On node start up, the location for the temporary files is printed to the standard output. <br><br>**Default:** Subdirectory of the first [store](#store)
 
 ### Networking

diff --git a/v20.2/install-cockroachdb-spatial.md b/v20.2/install-cockroachdb-spatial.md
@@ -1,6 +1,6 @@
 ---
 title: Install CockroachDB Spatial
-summary: Install instructions for CockroachDB with support for efficiently storing and querying spatial data.
+summary: Install CockroachDB with spatial libraries for efficiently storing and querying spatial data.
 toc: true
 ---
 
@@ -9,12 +9,10 @@ toc: true
 
 This page has instructions for installing CockroachDB Spatial on Mac and Linux.
 
-If you are looking to install a single-file CockroachDB binary without spatial support, see [Install CockroachDB](install-cockroachdb.html).
+If you are looking to install a single-file CockroachDB binary without [spatial features](spatial-features.html), see [Install CockroachDB](install-cockroachdb.html).
 
 {{site.data.alerts.callout_info}}
-These instructions are likely to change, since they refer to an alpha build of CockroachDB. Note that the Windows installation instructions for CockroachDB Spatial are still being developed.
-
-For instructions showing how to get started using CockroachDB Spatial, see [Working with Spatial Data](spatial-data.html).
+For instructions showing how to get started using CockroachDB Spatial, see [Working with Spatial Data](spatial-data.html).  For more information about supported spatial features, see [Spatial features](spatial-features.html)
 {{site.data.alerts.end}}
 
 <div class="filters clearfix">
@@ -28,17 +26,17 @@ For instructions showing how to get started using CockroachDB Spatial, see [Work
 
 {% include copy-clipboard.html %}
 ~~~ shell
-wget https://binaries.cockroachdb.com/cockroach-v20.2.0-beta.1.darwin-10.9-amd64.tgz
+wget https://binaries.cockroachdb.com/cockroach-v20.2.0-rc.4.darwin-10.9-amd64.tgz
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ shell
-tar xzvf cockroach-v20.2.0-beta.1.darwin-10.9-amd64.tgz
+tar xzvf cockroach-v20.2.0-rc.4.darwin-10.9-amd64.tgz
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ shell
-cd cockroach-v20.2.0-beta.1.darwin-10.9-amd64
+cd cockroach-v20.2.0-rc.4.darwin-10.9-amd64
 ~~~
 
 ## Step 2. Copy the binary and libraries to the appropriate locations
@@ -72,6 +70,10 @@ cp lib/libgeos.dylib /usr/local/lib/cockroach/
 cp lib/libgeos_c.dylib /usr/local/lib/cockroach/
 ~~~
 
+{{site.data.alerts.callout_info}}
+By default, CockroachDB looks for spatial libraries in `/usr/local/lib/cockroach`. You can change the location where CockroachDB looks for spatial libraries by passing the [`--spatial-libs` flag to `cockroach start`](cockroach-start.html#flags-spatial-libs).
+{{site.data.alerts.end}}
+
 ## Step 3. Test the installation
 
 To make sure that CockroachDB Spatial is properly installed and can execute spatial queries, do the steps listed below.
@@ -144,17 +146,17 @@ If you are having difficulties installing CockroachDB Spatial, please see our [S
 
 {% include copy-clipboard.html %}
 ~~~ shell
-wget https://binaries.cockroachdb.com/cockroach-v20.2.0-beta.1.linux-amd64.tgz
+wget https://binaries.cockroachdb.com/cockroach-v20.2.0-rc.4.linux-amd64.tgz
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ shell
-tar xzvf cockroach-v20.2.0-beta.1.linux-amd64.tgz
+tar xzvf cockroach-v20.2.0-rc.4.linux-amd64.tgz
 ~~~
 
 {% include copy-clipboard.html %}
 ~~~ shell
-cd cockroach-v20.2.0-beta.1.linux-amd64
+cd cockroach-v20.2.0-rc.4.linux-amd64
 ~~~
 
 ## Step 2. Copy the binary and libraries to the appropriate directories
@@ -188,6 +190,10 @@ cp lib/libgeos.so /usr/local/lib/cockroach/
 cp lib/libgeos_c.so /usr/local/lib/cockroach/
 ~~~
 
+{{site.data.alerts.callout_info}}
+By default, CockroachDB looks for spatial libraries in `/usr/local/lib/cockroach`. You can change the location where CockroachDB looks for spatial libraries by passing the [`--spatial-libs` flag to `cockroach start`](cockroach-start.html#flags-spatial-libs).
+{{site.data.alerts.end}}
+
 ## Step 3. Test that the installation works
 
 To make sure that CockroachDB Spatial is properly installed and can execute spatial queries, do the steps listed below.
@@ -256,13 +262,35 @@ If you are having difficulties installing CockroachDB Spatial, please see our [S
 
 ## See also
 
+- [Install CockroachDB](install-cockroachdb.html)
+- [Spatial Features](spatial-features.html)
+- [Spatial indexes](spatial-indexes.html)
+- [Spatial & GIS Glossary of Terms](spatial-glossary.html)
 - [Working with Spatial Data](spatial-data.html)
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)
 - [Migrate from GeoJSON](migrate-from-geojson.html)
 - [Migrate from GeoPackage](migrate-from-geopackage.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
-- [Spatial indexes](spatial-indexes.html)
-- [Spatial Features](spatial-features.html)
-- [Spatial & GIS Glossary of Terms](spatial-glossary.html)
-- [Geospatial functions](functions-and-operators.html#spatial-functions)
-- [Install CockroachDB](install-cockroachdb.html)
+- [Spatial functions](functions-and-operators.html#spatial-functions)
+- [POINT](point.html)
+- [LINESTRING](linestring.html)
+- [POLYGON](polygon.html)
+- [MULTIPOINT](multipoint.html)
+- [MULTILINESTRING](multilinestring.html)
+- [MULTIPOLYGON](multipolygon.html)
+- [GEOMETRYCOLLECTION](geometrycollection.html)
+- [Well known text](well-known-text.html)
+- [Well known binary](well-known-binary.html)
+- [GeoJSON](geojson.html)
+- [SRID 4326 - longitude and latitude](srid-4326.html)
+- [`ST_Contains`](st_contains.html)
+- [`ST_ConvexHull`](st_convexhull.html)
+- [`ST_CoveredBy`](st_coveredby.html)
+- [`ST_Covers`](st_covers.html)
+- [`ST_Disjoint`](st_disjoint.html)
+- [`ST_Equals`](st_equals.html)
+- [`ST_Intersects`](st_intersects.html)
+- [`ST_Overlaps`](st_overlaps.html)
+- [`ST_Touches`](st_touches.html)
+- [`ST_Union`](st_union.html)
+- [`ST_Within`](st_within.html)
diff --git a/v20.2/spatial-data.md b/v20.2/spatial-data.md
@@ -6,17 +6,13 @@ toc: true
 
 Supported [spatial](spatial-features.html) data types include:
 
-- Geometric objects such as points, lines, paths, and polygons in 2-dimensional space. These are projected onto the flat surface of a plane and are represented in SQL by the `GEOMETRY` data type.
+- Geometric objects such as [points](point.html), [lines](linestring.html), and [polygons](polygon.html) in 2-dimensional space. These are projected onto the flat surface of a plane and are represented in SQL by the `GEOMETRY` data type.
 
-- Geographic objects, which are also made up of points, lines, polygons, etc., in 2-dimensional space. They are projected onto the surface of a sphere and are represented in SQL by the `GEOGRAPHY` data type. (Technically, they are projected onto a spheroid: "a sphere with a bulge"). The spheroid projection means that:
+- Geographic objects, which are also made up of [points](point.html), [lines](linestring.html), [polygons](polygon.html), etc., in 2-dimensional space. They are projected onto the surface of a sphere and are represented in SQL by the `GEOGRAPHY` data type. (Technically, they are projected onto a spheroid: "a sphere with a bulge"). The spheroid projection means that:
 
     - The X and Y coordinates of 2-dimensional points are actually Longitude and Latitude values.
     - The paths between geographic objects are not straight lines; they are curves, and so the distances between objects are calculated using [great circle math](https://en.wikipedia.org/wiki/Great-circle_distance).
 
-{{site.data.alerts.callout_info}}
-This documentation is for an early alpha release. Be prepared for CockroachDB's spatial support and this documentation to change before the 20.2 GA release.
-{{site.data.alerts.end}}
-
 ## Getting started
 
 In this section, we'll describe how to:
@@ -26,20 +22,24 @@ In this section, we'll describe how to:
 
 ### Installation
 
-Currently, the best way to install a build of CockroachDB with support for spatial data is via [Docker](https://www.docker.com).
+An easy way to install a build of CockroachDB with support for spatial data is via [Docker](https://www.docker.com).
 
 Get the spatial build of CockroachDB:
 
 {% include copy-clipboard.html %}
 ~~~ shell
-docker pull cockroachdb/cockroach-unstable:v20.2.0-beta.2
+docker pull cockroachdb/cockroach-unstable:v20.2.0-rc.4
 ~~~
 
+{{site.data.alerts.callout_success}}
+For instructions showing other ways to install CockroachDB with spatial support, see [Install CockroachDB Spatial](install-cockroachdb-spatial.html).
+{{site.data.alerts.end}}
+
 Start the server:
 
 {% include copy-clipboard.html %}
 ~~~ shell
-docker run -d --name=geo --hostname=geo-host -p 26257:26257 -p 8080:8080  -v "${PWD}/cockroach-data/roach1:/cockroach/cockroach-data"  cockroachdb/cockroach-unstable:v20.2.0-beta.2 start-single-node --insecure
+docker run -d --name=geo --hostname=geo-host -p 26257:26257 -p 8080:8080  -v "${PWD}/cockroach-data/roach1:/cockroach/cockroach-data" cockroachdb/cockroach-unstable:v20.2.0-rc.4 start-single-node --insecure
 ~~~
 
 The example above uses some Docker networking and file location settings that map from the container to the host using CockroachDB's default network ports.
@@ -82,52 +82,33 @@ Next, convert the Shapefile data to SQL using the following command:
 shp2pgsql 1950-2018-torn-initpoint.shp > tornado-points.sql &
 ~~~
 
-#### Step 2. Edit the generated SQL so it can be imported
-
-In some cases, you can import your SQL spatial data files directly using the method in [Step 4](#step-4-import-the-tornado-data-into-the-tornadoes-database) below.
-
-However, you may encounter some errors loading arbitrary SQL files of spatial data into CockroachDB, since our spatial support is still in development. CockroachDB cannot always automatically execute the SQL statements generated by `shp2pgsql` or other tools, since those tools were designed for use with different databases.
-
-In order to get the file used in this example to load, execute the following `perl` commands in your shell. They will perform the necessary edits to the SQL file to get it to load (while taking backups of the file with the extension ".bak"):
-
-{% include copy-clipboard.html %}
-~~~ shell
-perl -p -i.bak -e 's/"1950-2018-torn-initpoint"/tornadoes/g' tornado-points.sql
-~~~
-
-{% include copy-clipboard.html %}
-~~~ shell
-perl -p -i.bak -e "s/'1950-2018-torn-initpoint'/'tornadoes'/g" tornado-points.sql
-~~~
-
-#### Step 3. Create the tornadoes database
-
-In your SQL client, create a `tornadoes` database so we have somewhere to put the data:
+#### Step 2. Create the tornadoes database
 
 {% include copy-clipboard.html %}
 ~~~ sql
 CREATE DATABASE tornadoes;
 USE tornadoes;
 ~~~
 
-#### Step 4. Import the tornado data into the tornadoes database
+#### Step 3. `IMPORT` the tornado data
 
-Then, use the SQL client to [execute the SQL statements in the file](cockroach-sql.html#execute-sql-statements-from-a-file) as shown below. The shell redirects are used to quiet most of the output, and the trailing `&` runs it as a background job in the shell.
+1. [Start a local file server](use-a-local-file-server-for-bulk-operations.html) in the directory where the file `tornado-points.sql` is located.
+
+2. From the [SQL client](cockroach-sql.html), import the data into CockroachDB using [`IMPORT PGDUMP`](import.html#import-a-postgres-database-dump):
 
 {% include copy-clipboard.html %}
-~~~ shell
-cockroach sql --insecure --database=tornadoes --port=26257 < tornado-points.sql 2>&1 1>/dev/null &
+~~~ sql
+IMPORT PGDUMP 'http://localhost:3000/tornado-points.sql';
 ~~~
 
-If the command executes successfully, you should see the following output:
-
 ~~~
-NOTICE: primary key changes are finalized asynchronously; further schema changes on this table may be restricted until the job completes
+        job_id       |  status   | fraction_completed | rows  | index_entries |  bytes
+---------------------+-----------+--------------------+-------+---------------+-----------
+  604425003155914753 | succeeded |                  1 | 63645 |             0 | 18287213
+(1 row)
 ~~~
 
-This means CockroachDB is executing the SQL statements in `tornado-points.sql`. It will take a few minutes to run. In most UNIX-like shells, you can check on the status of running jobs with the [`jobs(1)`](https://man7.org/linux/man-pages/man1/jobs.1p.html) command.
-
-#### Step 5. Query the tornado data
+#### Step 4. Query the tornado data
 
 Once the data has finished importing, we can query the tornado data from SQL.
 
@@ -141,7 +122,7 @@ We can try to verify this number against the NWS's tornado data set with the fol
 
 {% include copy-clipboard.html %}
 ~~~ sql
-SELECT COUNT(*)  FROM tornadoes WHERE yr = 1999 AND mo = 5 AND dy >= 02 AND dy <= 08;
+SELECT COUNT(*) FROM "1950-2018-torn-initpoint" WHERE yr = 1999 AND mo = 5 AND dy >= 02 AND dy <= 08;
 ~~~
 
 ~~~
@@ -157,7 +138,7 @@ Next, let's get a list of starting points for all of the tornadoes in the outbre
 
 {% include copy-clipboard.html %}
 ~~~ sql
-SELECT ST_AsText(geom) FROM tornadoes WHERE yr = 1999 AND st = 'OK' AND mo = 5 AND dy > 02 AND dy <= 08;
+SELECT ST_AsText(geom) FROM "1950-2018-torn-initpoint" WHERE yr = 1999 AND st = 'OK' AND mo = 5 AND dy > 02 AND dy <= 08;
 ~~~
 
 ~~~
@@ -313,7 +294,7 @@ In order to avoid full table scans, make sure to add [indexes](spatial-indexes.h
 - [`ST_Touches`](st_touches.html)
 - [`ST_Within`](st_within.html)
 
-To use a version of a function from the list above that will explicitly *not* use the index, add an underscore (`_`) to the beginning of the function name, e.g., `_ST_Covers`.
+To use a version of a function from the list above that will explicitly *not* use the index, add an underscore (`_`) to the beginning of the function name, e.g., [`_ST_Covers`](st_covers.html).
 
 You can check which queries are using which indexes using the [`EXPLAIN`](explain.html) statement. For more information about general query tuning (including index usage), see [Make queries fast](make-queries-fast.html).
 
@@ -335,12 +316,36 @@ If you encounter behavior that you think is due to a performance issue, please g
 ## See also
 
 - [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
+- [Spatial Features](spatial-features.html)
+- [Spatial indexes](spatial-indexes.html)
+- [Spatial & GIS Glossary of Terms](spatial-glossary.html)
+- [Working with Spatial Data](spatial-data.html)
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)
 - [Migrate from GeoJSON](migrate-from-geojson.html)
 - [Migrate from GeoPackage](migrate-from-geopackage.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
-- [Spatial indexes](spatial-indexes.html)
-- [Spatial and GIS Glossary of Terms](spatial-glossary.html)
 - [Spatial functions](functions-and-operators.html#spatial-functions)
+- [POINT](point.html)
+- [LINESTRING](linestring.html)
+- [POLYGON](polygon.html)
+- [MULTIPOINT](multipoint.html)
+- [MULTILINESTRING](multilinestring.html)
+- [MULTIPOLYGON](multipolygon.html)
+- [GEOMETRYCOLLECTION](geometrycollection.html)
+- [Well known text](well-known-text.html)
+- [Well known binary](well-known-binary.html)
+- [GeoJSON](geojson.html)
+- [SRID 4326 - longitude and latitude](srid-4326.html)
+- [`ST_Contains`](st_contains.html)
+- [`ST_ConvexHull`](st_convexhull.html)
+- [`ST_CoveredBy`](st_coveredby.html)
+- [`ST_Covers`](st_covers.html)
+- [`ST_Disjoint`](st_disjoint.html)
+- [`ST_Equals`](st_equals.html)
+- [`ST_Intersects`](st_intersects.html)
+- [`ST_Overlaps`](st_overlaps.html)
+- [`ST_Touches`](st_touches.html)
+- [`ST_Union`](st_union.html)
+- [`ST_Within`](st_within.html)
 - [Troubleshooting overview](troubleshooting-overview.html)
 - [Support resources](support-resources.html)