Skip to content

feat: add h3 container image#227

Open
jmealo wants to merge 1 commit into
cloudnative-pg:mainfrom
jmealo:dev/h3
Open

feat: add h3 container image#227
jmealo wants to merge 1 commit into
cloudnative-pg:mainfrom
jmealo:dev/h3

Conversation

@jmealo
Copy link
Copy Markdown

@jmealo jmealo commented May 29, 2026

What this adds

A container image for the core h3 PostgreSQL extension (h3-pg), which provides bindings for H3, Uber's hierarchical hexagonal geospatial indexing system. This enables CloudNativePG users to: index, aggregate, and join location data on a global hexagonal grid directly in SQL.

Closes #226

Details

  • Package: postgresql-<pg-major>-h3 (PGDG)
  • trixie: 4.2.3-4.pgdg13+1 · bookworm: 4.2.3-4.pgdg12+1
  • SQL version: 4.2.3 (default_version in h3.control)
  • PostgreSQL / distros: 18 on bookworm and trixie, linux/amd64 + linux/arm64
  • Scope: ships only the self-contained core h3 extension. The optional h3_postgis companion (which requires PostGIS) is intentionally excluded.
  • System library: h3.so dynamically links libh3.so.1 (from libh3-1, also PGDG). It is bundled under /system and exposed via ld_library_path = ["system"], mirroring the postgis image. auto_update_os_libs is enabled with system-libs/ manifests for renovate.

⚠️ License note (please review)

Both h3-pg and libh3/uber/h3 are Apache-2.0 upstream. However, the Debian libh3-1 package's copyright file classifies two upstream files (README.md, src/h3lib/lib/coordijk.c) as AGPL-3+, attributing them to DGGRID / Southern Oregon University. This looks like an over-conservative Debian classification of an algorithm-origin credit: current upstream uber/h3 carries Apache-2.0 headers on those files and contains no AGPL text. Because coordijk.c compiles into the bundled libh3.so.1 and the Debian copyright ships under /licenses/, it is surfaced for maintainer review
(also raised in #226).

Testing

  • task e2e:test:full TARGET=h3passing: builds the multi-arch image, pushes to a local registry, deploys a CNPG Cluster with the h3 image volume + a Database, and asserts CREATE EXTENSION h3 (v4.2.3) applies cleanly.
  • Multi-arch build (linux/amd64 + linux/arm64) and push verified for both bookworm and trixie.

Submission checklist

  • Commit is DCO signed-off (git commit -s)
  • PR targets the main branch of the upstream repository
  • Adds a CODEOWNERS entry for /h3/
  • Single squashed commit following the required feat: format

Add a container image for the core `h3` PostgreSQL extension (h3-pg),
which provides bindings for Uber's H3 hierarchical hexagonal geospatial
indexing system, allowing CloudNativePG users to index and query
location data on an H3 grid directly in SQL.

The image bundles the `postgresql-NN-h3` package together with its
required `libh3` system library (exposed via ld_library_path), built
for PostgreSQL 18 on bookworm and trixie. Only the self-contained core
`h3` extension is shipped; the optional `h3_postgis` companion, which
requires PostGIS, is intentionally excluded.

Closes cloudnative-pg#226

Signed-off-by: Jeff Mealo <jmealo@protonmail.com>
@jmealo jmealo requested review from a team and NiccoloFei as code owners May 29, 2026 19:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[New Extension]: h3

1 participant