Upgrade H3 core to v4 (#54)

Update `h3` core library to `v4.0.0`. Almost all functions have been renamed to align with `h3` core `v4`. Please take care when updating.

.github/docker/Dockerfile

@@ -1,18 +1,22 @@
-ARG ARCH=amd64
-ARG UBUNTU=latest
-FROM $ARCH/ubuntu:$UBUNTU
+ARG UBUNTU=focal
+FROM ubuntu:$UBUNTU
 
-ARG ARCH
 ARG UBUNTU
 ENV DEBIAN_FRONTEND=noninteractive
-ENV ARCH=$ARCH
 
 RUN apt-get update && apt-get install -y \
     build-essential \
-    cmake \
+    # cmake \ # see following comments
     git \
     pgxnclient
 
+# H3 requires CMake 3.20, which has not landed in ubuntu
+# as of writing. So we setup cmake apt repository
+RUN if [ "$UBUNTU" != "impish" ] ; then apt-key adv --fetch-keys https://apt.kitware.com/keys/kitware-archive-latest.asc ; fi
+RUN if [ "$UBUNTU" != "impish" ] ; then echo "deb https://apt.kitware.com/ubuntu/ ${UBUNTU} main" >> /etc/apt/sources.list.d/pgdg.list ; fi
+RUN apt-get update && apt-get install -y cmake
+# we can remove the block above when 3.20 lands
+
 # Setup PostgreSQL apt repository
 RUN apt-key adv --fetch-keys https://www.postgresql.org/media/keys/ACCC4CF8.asc
 RUN echo "deb http://apt.postgresql.org/pub/repos/apt/ ${UBUNTU}-pgdg main" >> /etc/apt/sources.list.d/pgdg.list

.github/docker/tools.sh

@@ -2,12 +2,12 @@
 set -e
 
 BASEDIR=$(dirname $(realpath "$0"))
-REPOSITORY="docker.pkg.github.com/bytesandbrains/h3-pg"
+REPOSITORY="ghcr.io/bytesandbrains/h3-pg"
 
 # i386 being phased out from postgres apt :-(
 #ARCHS=(amd64 i386)
 ARCHS=(amd64)
-UBUNTUS=(impish focal) # latest and LTS
+UBUNTUS=(jammy focal) # latest and LTS
 POSTGRESQLS=(14 13) # two latest
 
 cd $BASEDIR
@@ -49,6 +49,7 @@ case "${o}" in
             echo "$postgresql-$ubuntu-$arch"
             docker build \
               --tag $REPOSITORY/test:$postgresql-$ubuntu-$arch \
+              --platform linux/$arch \
               --build-arg POSTGRESQL=$postgresql \
               --build-arg UBUNTU=$ubuntu \
               --build-arg ARCH=$arch \
@@ -81,6 +82,7 @@ case "${o}" in
             echo "$postgresql-$ubuntu-$arch"
             docker run \
               --rm \
+              --platform linux/$arch \
               -v "$PWD"/../..:/github/workspace \
               $REPOSITORY/test:$postgresql-$ubuntu-$arch
           done

.github/documentation/generate.py

@@ -136,6 +136,9 @@ def string(self, s):
     def fun_name(self, children):
         return children[1]
 
+    def datatype(self, children):
+        return children[0]
+
     @v_args(inline=True)
     def argument(self, name, argtype, default=None):
         out = ""

.github/documentation/sql.lark

@@ -29,7 +29,7 @@ create_type_stmt: "CREATE" "TYPE" CNAME ("(" /([^\)])+/ ")")?
 
 // -----------------------------------------------------------------------------
 // CREATE CAST ...
-create_cast_stmt: "CREATE" "CAST" "(" CNAME "AS" CNAME ")" "WITH" "FUNCTION" CNAME "(" /([^\)])+/ ")"
+create_cast_stmt: "CREATE" "CAST" "(" datatype "AS" datatype ")" "WITH" "FUNCTION" CNAME "(" /([^\)])+/ ")"
 
 // -----------------------------------------------------------------------------
 // CREATE OPERATOR CLASS name [ DEFAULT ] FOR TYPE data_type
@@ -53,8 +53,8 @@ create_opcl_list: create_opcl_opts ("," create_opcl_opts)*
 // )
 create_oper_stmt: "CREATE" "OPERATOR" OPERATOR "(" create_oper_opts ")"
 create_oper_opt: /PROCEDURE/ "=" CNAME
-               | /LEFTARG/ "=" CNAME
-               | /RIGHTARG/ "=" CNAME
+               | /LEFTARG/ "=" datatype
+               | /RIGHTARG/ "=" datatype
                | /COMMUTATOR/ "=" OPERATOR
                | /NEGATOR/ "=" OPERATOR
                | /RESTRICT/ "=" CNAME
@@ -82,7 +82,7 @@ create_oper_opts: create_oper_opt ("," create_oper_opt)*
 //   } ...
 //     [ WITH ( attribute [, ...] ) ]
 create_func_stmt: "CREATE" ("OR" "REPLACE")? "FUNCTION" fun_name "(" [argument_list] ")" [create_fun_rets] create_fun_opts*
-?create_fun_rets: "RETURNS" ("SETOF")? CNAME "[]"?
+?create_fun_rets: "RETURNS" ("SETOF")? datatype "[]"?
 create_fun_opts: "LANGUAGE" CNAME
               | ("IMMUTABLE" | "STABLE" | "VOLATILE" | ("NOT"? "LEAKPROOF"))
               | (("CALLED" "ON" "NULL" "INPUT") | ("RETURNS" "NULL" "ON" "NULL" "INPUT") | "STRICT")
@@ -102,13 +102,31 @@ argument_list: argument ("," argument)*
 //   ...
 // } IS 'text'
 comment_on_stmt: "COMMENT" "ON" comment_on_type "IS" string
-comment_on_type: "CAST" "(" CNAME "AS" CNAME ")" -> comment_on_cast
+comment_on_type: "CAST" "(" datatype "AS" datatype ")" -> comment_on_cast
                | "FUNCTION" fun_name "(" [argument_list] ")" -> comment_on_function
                | "OPERATOR" OPERATOR "(" argument "," argument ")" -> comment_on_operator
 
 // -----------------------------------------------------------------------------
 // SIMPLE RULES
-argument: "OUT"? [CNAME] CNAME "[]"? ("DEFAULT" expr)?
+argument: "OUT"? [CNAME] datatype "[]"? ("DEFAULT" expr)?
+!datatype: "h3index"
+        | "bigint"
+        | "boolean"
+        | "cstring"
+        | "double" "precision"
+        | "float"
+        | "geography"
+        | "geometry"
+        | "int"
+        | "int32"
+        | "int8"
+        | "integer"
+        | "internal"
+        | "point"
+        | "polygon"
+        | "record"
+        | "text"
+        | "void"
 fun_name: [CNAME "."] CNAME
 ?expr: atom | string
 atom: SIGNED_NUMBER -> number

.github/workflows/test.yml

@@ -4,7 +4,7 @@ on: [push, pull_request]
 
 jobs:
   docs:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-python@v2
@@ -14,21 +14,21 @@ jobs:
       - run: git diff --exit-code docs
 
   installcheck:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     strategy:
       matrix:
         postgresql: [14, 13]
-        ubuntu: [impish, focal]
+        ubuntu: [jammy, focal]
         arch: [amd64]
     steps:
       - uses: actions/checkout@v2
       - name: Login to repository
-        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login docker.pkg.github.com -u "$GITHUB_ACTOR" --password-stdin
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
       - name: Test
-        run: docker run -v ${PWD}:/github/workspace docker.pkg.github.com/bytesandbrains/h3-pg/test:${{ matrix.postgresql }}-${{ matrix.ubuntu }}-${{ matrix.arch }}
+        run: docker run -v ${PWD}:/github/workspace ghcr.io/bytesandbrains/h3-pg/test:${{ matrix.postgresql }}-${{ matrix.ubuntu }}-${{ matrix.arch }}
 
   i386:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-20.04
     strategy:
       matrix:
         postgresql: [12]
@@ -37,6 +37,6 @@ jobs:
     steps:
       - uses: actions/checkout@v2
       - name: Login to repository
-        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login docker.pkg.github.com -u "$GITHUB_ACTOR" --password-stdin
+        run: echo "${{ secrets.GITHUB_TOKEN }}" | docker login ghcr.io -u "$GITHUB_ACTOR" --password-stdin
       - name: Test
-        run: docker run -v ${PWD}:/github/workspace docker.pkg.github.com/bytesandbrains/h3-pg/test:${{ matrix.postgresql }}-${{ matrix.ubuntu }}-${{ matrix.arch }}
+        run: docker run -v ${PWD}:/github/workspace ghcr.io/bytesandbrains/h3-pg/test:${{ matrix.postgresql }}-${{ matrix.ubuntu }}-${{ matrix.arch }}

.gitignore

@@ -8,7 +8,7 @@ h3/test/regression.*
 h3/test/results
 
 # Generated
-/h3--*.sql
+/h3*.sql
 /h3/src/include/extension.h
 /h3/test/expected/ci-*.out
 /h3/test/sql/ci-*.sql

CHANGELOG.md

@@ -26,10 +26,16 @@ avoid adding features or APIs which do not map onto the
     Click to see more.
   </summary>
 
-- Handle non-polygons for `h3_polyfill` (see [#55], thanks [@Lokks])
-
 </details>
 
+## [4.0.0] - 2022-08-24
+
+- ⚠️ Update `h3` core library to `v4.0.0`. Almost all functions have been renamed to align with `h3` core `v4`. Please take care when updating. You can see a [list of changed function names](https://h3geo.org/docs/library/migration-3.x/functions) in the core library documentation.
+- ⚠️ The PostGIS functions has been extracted into a separate extension `h3_postgis`. Install using `CREATE EXTENSION h3_postgis;`.
+- Enable link time optimization (see [#75], thanks [@mngr777])
+- Handle non-polygons for `h3_polyfill` (see [#55], thanks [@Lokks])
+- Take advantage of the new v4 error codes (fixes [#71], thanks [@kalenikaliaksandr])
+
 ## [3.7.2] - 2022-04-13
 
 - Allow `NULL` in `holes` array for `h3_polyfill` (see [#64], thanks [@mngr777])
@@ -153,7 +159,8 @@ avoid adding features or APIs which do not map onto the
 
 - Initial public release
 
-[unreleased]: https://github.com/bytesandbrains/h3-pg/compare/v3.7.2...HEAD
+[unreleased]: https://github.com/bytesandbrains/h3-pg/compare/v4.0.0...HEAD
+[4.0.0]: https://github.com/bytesandbrains/h3-pg/compare/v3.7.2...v4.0.0
 [3.7.2]: https://github.com/bytesandbrains/h3-pg/compare/v3.7.1...v3.7.2
 [3.7.1]: https://github.com/bytesandbrains/h3-pg/compare/v3.7.0...v3.7.1
 [3.7.0]: https://github.com/bytesandbrains/h3-pg/compare/v3.6.5...v3.7.0
@@ -191,9 +198,12 @@ avoid adding features or APIs which do not map onto the
 [#55]: https://github.com/bytesandbrains/h3-pg/issues/55
 [#64]: https://github.com/bytesandbrains/h3-pg/issues/64
 [#65]: https://github.com/bytesandbrains/h3-pg/pull/65
+[#71]: https://github.com/bytesandbrains/h3-pg/issues/71
+[#75]: https://github.com/bytesandbrains/h3-pg/pull/75
 [@abelvm]: https://github.com/AbelVM
-[@komzpa]: https://github.com/Komzpa
+[@kalenikaliaksandr]: https://github.com/kalenikaliaksandr
 [@kmacdough]: https://github.com/kmacdough
-[@trylinka]: https://github.com/trylinka
-[@mngr777]: https://github.com/mngr777
+[@komzpa]: https://github.com/Komzpa
 [@lokks]: https://github.com/Lokks
+[@mngr777]: https://github.com/mngr777
+[@trylinka]: https://github.com/trylinka

META.json

@@ -2,15 +2,15 @@
   "name": "h3",
   "abstract": "PostgreSQL bindings for H3",
   "description": "PostgreSQL bindings for H3, a hierarchical hexagonal geospatial indexing system.",
-  "version": "unreleased",
+  "version": "4.0.0",
   "maintainer": "Bytes & Brains <[email protected]>",
   "license": "apache_2_0",
   "provides": {
     "h3": {
       "abstract": "PostgreSQL bindings for H3",
-      "file": "sql/h3--unreleased.sql",
+      "file": "sql/h3--4.0.0.sql",
       "docfile": "README.md",
-      "version": "unreleased"
+      "version": "4.0.0"
     }
   },
   "resources": {

Makefile

@@ -1,4 +1,4 @@
-# Copyright 2018-2019 Bytes & Brains
+# Copyright 2018-2022 Bytes & Brains
 # 
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -12,14 +12,14 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-EXTENSION = h3
+EXTENSION = h3 h3_postgis
 
 # extract extension version from .control file
-EXTVERSION = $(shell grep default_version $(EXTENSION).control | \
+EXTVERSION = $(shell grep default_version h3.control | \
 	sed -e "s/default_version[[:space:]]*=[[:space:]]*'\([^']*\)'/\1/")
 
 # h3 core library version to clone and statically link
-LIBH3_VERSION = v3.7.1
+LIBH3_VERSION = v4.0.0-rc5
 # directory that h3 core repository is cloned into
 LIBH3_SOURCE = libh3-$(LIBH3_VERSION)
 # h3 static library location
@@ -28,15 +28,19 @@ LIBH3_BUILD = $(LIBH3_SOURCE)/build
 SQL_INSTALLS = $(wildcard h3/sql/install/*.sql)
 SQL_UPDATES = $(wildcard h3/sql/updates/*.sql)
 SQL_TESTS = $(wildcard h3/test/sql/*.sql)
-SQL_FULLINSTALL = $(EXTENSION)--$(EXTVERSION).sql
+SQL_FULLINSTALL = h3--$(EXTVERSION).sql
+
+# postgis extension
+SQL_INSTALLS_H3_POSTGIS = $(wildcard h3_postgis/sql/install/*.sql)
+SQL_FULLINSTALL_H3_POSTGIS = h3_postgis--$(EXTVERSION).sql
 
 # a shared library to build from multiple source files
-MODULE_big = $(EXTENSION)
+MODULE_big = h3
 # object files to be linked together
 OBJS = $(patsubst %.c,%.o,$(wildcard h3/src/lib/*.c))
 # random files to install into $PREFIX/share/$MODULEDIR
 DATA = $(SQL_UPDATES)
-DATA_built = $(SQL_FULLINSTALL)
+DATA_built = $(SQL_FULLINSTALL) $(SQL_FULLINSTALL_H3_POSTGIS)
 # will be added to MODULE_big link line
 SHLIB_LINK += -lh3 -L$(LIBH3_BUILD)/lib
 # will be added to CPPFLAGS
@@ -47,13 +51,12 @@ REGRESS = $(basename $(notdir $(SQL_TESTS)))
 REGRESS_OPTS = \
 	--inputdir=h3/test \
 	--outputdir=h3/test \
-	--load-extension=postgis \
 	--load-extension=h3
 # extra files to remove in make clean
 EXTRA_CLEAN += \
 	$(LIBH3_SOURCE) \
 	$(DATA_built) \
-	src/include/extension.h \
+	h3/src/include/extension.h \
 	$(wildcard h3/test/sql/ci-*.sql) \
 	$(wildcard h3/test/expected/ci-*.out) \
 	$(wildcard *.BAK) \
@@ -100,10 +103,16 @@ h3/src/include/extension.h: h3/src/include/extension.in.h
 # generate full installation sql (from uninstalled to latest)
 $(SQL_FULLINSTALL): $(sort $(SQL_INSTALLS))
 	cat $^ > $@
+$(SQL_FULLINSTALL_H3_POSTGIS): $(sort $(SQL_INSTALLS_H3_POSTGIS))
+	cat $^ > $@
 
 # package for distribution
-dist: $(SQL_FULLINSTALL)
-	git archive --prefix=h3-$(EXTVERSION)/ --output h3-${EXTVERSION}.zip --add-file=$(SQL_FULLINSTALL) HEAD
+dist: $(SQL_FULLINSTALL) $(SQL_FULLINSTALL_H3_POSTGIS)
+	git archive --prefix=h3-$(EXTVERSION)/ \
+				--output h3-${EXTVERSION}.zip \
+				--add-file=$(SQL_FULLINSTALL) \
+				--add-file=$(SQL_FULLINSTALL_H3_POSTGIS) \
+				HEAD
 
 ###########################################################################
 # Extra CI testing targets
@@ -112,6 +121,8 @@ dist: $(SQL_FULLINSTALL)
 format: clean
 	pgindent
 
+# Run on dev using:
+# PIPENV_PIPFILE=.github/documentation/Pipfile pipenv run make docs/api.md
 docs/api.md: $(SQL_INSTALLS)
 	python .github/documentation/generate.py "h3/sql/install/*" > $@
 	npx doctoc $@
@@ -126,11 +137,11 @@ EXCLUDED_BINDING_FUNCTIONS = \
 # functions provided that are not part of expected binding functions
 EXTRA_BINDING_FUNCTIONS = \
 	get_extension_version \
-	to_children_slow \
-	to_geo_boundary_geography \
-	to_geo_boundary_geometry \
-	to_geography \
-	to_geometry
+	cell_to_children_slow \
+	cell_to_geo_boundary_geography \
+	cell_to_geo_boundary_geometry \
+	cell_to_geography \
+	cell_to_geometry
 
 /tmp/excluded-functions:
 	echo "$(EXCLUDED_BINDING_FUNCTIONS)" | tr " " "\n" > $@
@@ -141,7 +152,7 @@ EXTRA_BINDING_FUNCTIONS = \
 PRINT_TYPES_SQL = "SELECT typname, typlen, typbyval, typalign FROM pg_type WHERE typname LIKE '%h3index' ORDER BY typname;"
 PRINT_FUNCTIONS_SQL = "\df *h3*"
 PRINT_FUNCFLAGS_SQL = "SELECT proname, proisstrict, provolatile, proparallel, prosrc FROM pg_proc WHERE proname LIKE '%h3%' ORDER BY proname, prosrc;"
-PRINT_OPERATORS_SQL = "\do"
+PRINT_OPERATORS_SQL = "\do *h3*"
 
 # rules for testing the update path against full install
 h3/test/sql/ci-install.sql: $(SQL_FULLINSTALL)