Install PostGIS for AlloyDB Omni

This page describes how to manually add the PostGIS extension to an existing AlloyDB Omni installation. The PostGIS extension enables storing, indexing, and querying geospatial data.

You can install PostGIS using either of the following methods:

  • Use Debian options in the Docker or Podman CLI. Docker relies on a daemon and requires root privileges for most operations, while Podman is daemonless and rootless.
  • Use Red Hat Universal Base Images (UBI). UBI container base operating system images are built from parts of Red Hat Enterprise Linux (RHEL).

Before you begin

Install AlloyDB Omni on your system.

Add PostGIS to your AlloyDB Omni installation

To add the PostGIS extension to your AlloyDB Omni installation, follow these steps:

  1. Find your installed AlloyDB Omni version labels:

    Docker

    docker run --rm -it  google/alloydbomni cat VERSION.txt
    

    Podman

    podman run --rm -it  google/alloydbomni cat VERSION.txt
    

    The output is similar to the following:

    AlloyDB Omni version: 16.3.0
    

    Take note of the AlloyDB Omni version number because you need it in the next step.

  2. Set the OMNI_VERSION environment variable:

    OMNI_VERSION=VERSION
    

    Replace VERSION with the complete database server version from the previous step, for example, 16.3.0.

  3. Build a custom Docker image that includes the PostGIS extension:

    mkdir ~/alloydb-omni-postgis
    
    cd ~/alloydb-omni-postgis
    
    sudo dnf install -y subscription-manager
    
    sudo subscription-manager register --username EMAIL --password PASSWORD --auto-attach
    
    sudo mkdir -p entitlement rhsm-conf rhsm-ca
        sudo cp -r /etc/pki/entitlement/* entitlement/
        sudo cp -r /etc/rhsm/rhsm.conf rhsm-conf/
        sudo cp -r /etc/rhsm/ca/* rhsm-ca/
    
    cat <<EOF > Dockerfile
        FROM google/alloydbomni:16.3.0-ubi
        COPY ./entitlement /etc/pki/entitlement
        COPY ./rhsm-conf /etc/rhsm
        COPY ./rhsm-ca /etc/rhsm/ca
        RUN arch=$(uname -m) && \
            subscription-manager repos --enable codeready-builder-for-rhel-9-${arch}-rpms && \
            dnf install -y \
            https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-${arch}/pgdg-redhat-repo-latest.noarch.rpm && \
            dnf install -y postgresql16-server postgis34_16 && \
            dnf clean all
        # On RHEL-based systems, PostgreSQL extensions like Orafce and PostGIS are typically installed in /usr/pgsql-16/share/extension and /usr/pgsql-16/lib.
        # This step creates symbolic links to those files in the paths expected by AlloyDB Omni,
        # which lets AlloyDB Omni locate extension control files and shared libraries without duplicating data.
        RUN for file in /usr/pgsql-16/share/extension/*; do \
           target="/usr/lib/postgresql/16/share/extension/$(realpath -m --relative-to=/usr/pgsql-16/share/extension/ "$file")"; \
           if [ ! -e "$target" ]; then \
              ln -s "$file" "$target" || (echo "Failed to link \"$file\" to \"$target\", exiting." && exit 1); \
           else \
              echo "$target already exists"; \
           fi; \
        done && \
        for file in /usr/pgsql-16/lib/*; do \
           target="/usr/lib/postgresql/16/lib/$(realpath -m --relative-to=/usr/pgsql-16/lib/ "$file")"; \
           if [ ! -e "$target" ]; then \
              ln -s "$file" "$target" || (echo "Failed to link \"$file\" to \"$target\", exiting." && exit 1); \
           else \
              echo "$target already exists"; \
           fi; \
        done
    EOF
    

  4. Create a new container with AlloyDB Omni named my-omni-postgis:

    Docker

    docker build -t google/alloydbomni-with-postgis:latest
    docker run --name my-omni-postgis  -e POSTGRES_PASSWORD=NEW_PASSWORD  -d google/alloydbomni-with-postgis:OMNI_VERSION
    

    Podman

    podman run --name my-omni-postgis  -e POSTGRES_PASSWORD=NEW_PASSWORD  -d google/alloydbomni-with-postgis:OMNI_VERSION
    
  5. Connect to your database with the PostGIS extension:

    docker exec -it my-omni-postgis psql -h localhost -U postgres
    
  6. Enable PostGIS:

    CREATE EXTENSION IF NOT EXISTS POSTGIS;
    SELECT postgis_full_version();
    

    The output looks similar to the following:

    postgres=# SELECT postgis_full_version();
    postgis_full_version
    --------------------------------------------------------------------------------------------------------------------------------
    POSTGIS="3.3.2 4975da8" [EXTENSION] PGSQL="150" GEOS="3.11.1-CAPI-1.17.1" PROJ="9.1.1" LIBXML="2.9.14" LIBJSON="0.16" LIBPROTOBUF="1.4.1" WAGYU="0.5.0 (Internal)"
    (1 row)