README.pg_sphere

pgSphere is a PostgreSQL extension for spherical geometry.

It provides:

* New data types (points, spherical polygons, paths, circles, ellipses, coordinate ranges)
* Input and output of data in various formats
* Membership, overlap, and other operators
* Circumference and area of objects
* Object rotation by Euler angles
* Indexing of spherical data types

This is an R-tree implementation using GiST for spherical objects like
spherical points and spherical circles with useful functions and operators.
It also supports the Block Range INdexing (BRIN) for large datasets.

NOTICE:
     This version will work only with PostgreSQL version 10 and above.

VERSIONING:

Stable versions are marked with tags containing version numbers in the GitHub
repository at https://github.com/postgrespro/pgsphere/. Each stable version
contains upgrade scripts for updating an existing installation to the latest
version using the ALTER EXTENSION UPDATE TO command.

The master branch is intended for development purposes and may contain
intermediate changes. The current version in the master branch and its
functionality are subject to change.

Note: The master branch should not be used in production because the upgrade
scripts and the current version number may be changed.

INSTALLATION:

  -- Build and install

  make
  make install

  -- HEALPix/MOC support is included by default. If your platform does not
  -- have the required libhealpix_cxx dependency, you can optionally build
  -- pgSphere without HEALPix/MOC support, like this:

  make USE_HEALPIX=0
  make USE_HEALPIX=0 install

  -- Load extension

  psql -c "CREATE EXTENSION pg_sphere;" <database>

UPDATING AN EXISTING INSTALLATION:

  -- If you are updating from a previous version of pgSphere, perform the
  -- same make and make install steps as above, but, instead of the CREATE
  -- EXTENSION step, you need to do:

  psql -c "ALTER EXTENSION pg_sphere UPDATE TO 'A.B.C';" <database>

  -- where A.B.C is a placeholder for the current version.
  -- You also may want to check what version of pgSphere is installed using
     either or both of the following commands:

  psql -c "SELECT pg_sphere_version();" <database>
  psql -c "SELECT * FROM pg_available_extension_versions WHERE name = 'pg_sphere';"

REGRESSION TEST (as the same user as the currently running PostgreSQL server):

  make installcheck

  -- or --

  make USE_HEALPIX=0 installcheck

LONG REGRESSION TEST:

  make crushtest

  -- or --

  make USE_HEALPIX=0 crushtest

The 'make' program used in all of the above commands must be compatible with
GNU make.

For more information or to report issues or to help with development, please
refer to https://github.com/postgrespro/pgsphere/

Original repository for pgSphere: https://github.com/akorotkov/pgsphere

Have a lot of fun!