postgis-with-extensions

PostgreSQL images based on postgis/postgis, with more than a hundred extra extensions. Published on Docker Hub (ivanlonel/postgis-with-extensions) and GHCR (ghcr.io/ivanlonel/postgis-with-extensions).

Tags

Tags follow the pattern X-Y.Z, where X is the PostgreSQL major version and Y.Z the PostGIS major.minor version.

• 14-3.7, 15-3.7, 16-3.7, 17-3.7, 18-3.7: rebuilt every week from the matching postgis/postgis image, with the latest packages. latest is 18-3.7.
• 14-3.7-full to 18-3.7-full (full is 18-3.7-full): the same images plus heavier extensions, such as Citus, DocumentDB, pg_duckdb, pg_search, PL/Java and PL/R.
• 14-3.6 to 18-3.6: final release, no longer updated, like upstream's 3.6 images.

The images follow upstream's Debian tags (amd64 only): when postgis/postgis adds or drops a PostgreSQL or PostGIS version, so does this repository.

[!IMPORTANT] From the 3.7 images on, nothing is preloaded by default. Extensions that need shared_preload_libraries (such as TimescaleDB, pg_cron or PoWA) only work once enabled with SHARED_PRELOAD_LIBRARIES. SHARED_PRELOAD_LIBRARIES=legacy brings back the list earlier images preloaded on new clusters. Clusters created with earlier images keep their own configuration.

Usage

docker run -e POSTGRES_PASSWORD=mysecretpassword -e SHARED_PRELOAD_LIBRARIES=all -d ivanlonel/postgis-with-extensions

compose_example defines a stack with a powa-web and a pgAdmin container. It extends this image with localedef, so PostgreSQL uses the locale set in compose.yaml.

The postgres image documentation explains how to configure and run the container. From PostgreSQL 18 on, mount the data volume at /var/lib/postgresql (not /var/lib/postgresql/data).

Enabling libraries that need preloading

SHARED_PRELOAD_LIBRARIES takes a comma-separated list of libraries (or the presets all and legacy) and is applied on every start, so changing it and restarting the container is enough to enable or disable a library:

docker run -e POSTGRES_PASSWORD=mysecretpassword -e SHARED_PRELOAD_LIBRARIES=timescaledb,pg_cron,powa -d ivanlonel/postgis-with-extensions

• all preloads every library of the extension tables' Preload column that the image ships for its PostgreSQL version, except the opt-in ones (marked so); legacy preloads the list the images preloaded by default before 3.7.
• DocumentDB (-full images) is opt-in (SHARED_PRELOAD_LIBRARIES=all,pg_documentdb adds it): until CREATE EXTENSION documentdb has run in pg_cron's database, its background worker makes every DROP DATABASE wait up to 10 seconds.
• Citus (-full images) is opt-in too (SHARED_PRELOAD_LIBRARIES=citus). It must load before every other library, so it's put first, ahead of the cluster's own list.
• So is pg_auto_failover's monitor library (pgautofailover): on PostgreSQL 15 and later, its background workers make DROP DATABASE hang for as long as it's preloaded (pg_auto_failover#1063, fixed upstream after 2.2, unreleased yet). pg_autoctl create monitor runs a monitor in an instance of its own, which doesn't need it.
• pg_savior and pg_statement_rollback change how statements behave, so they're preloaded switched off: turn them on with pg_savior.enabled = on or pg_statement_rollback.enabled = on, per session, role or database.
• Preloaded, pgsodium and Supabase Vault read a root key from $(pg_config --sharedir)/extension/pgsodium_getkey. The image's script generates one and keeps it in the data directory (pgsodium_root.key), next to the data it protects: for real protection, point pgsodium.getkey_script and vault.getkey_script at a script that fetches the key from a key manager.
• Libraries required by others come along: powa brings PoWA's statistics extensions, pg_documentdb brings pg_documentdb_core, pg_documentdb_extended_rum and pg_cron, vectorize brings pg_cron.
• The variable only adds libraries: those the cluster's own configuration preloads stay loaded. To remove one of those, edit the configuration, e.g. ALTER SYSTEM SET shared_preload_libraries = '...', and restart.
• The settings a library relies on come along too (for instance cron.database_name), unless the configuration already sets them; options passed on the command line (postgres -c name=value) always win.
• An unknown library name stops the container with an error listing the valid ones. Any library installed in PostgreSQL's library directory is accepted, such as auto_explain.

Environment variables

Besides the postgres image variables:

Variable	Default	Description
SHARED_PRELOAD_LIBRARIES		Libraries to add to shared_preload_libraries on every start (see above).
PG_CRON_DB	POSTGRES_DB	pg_cron's database (cron.database_name).
PG_PARTMAN_DB	POSTGRES_DB	pg_partman background worker's database (pg_partman_bgw.dbname).
POWA_LOCAL_SNAPSHOT	YES	NO sets PoWA up for remote snapshots: its statistics extensions are preloaded, not its own worker.
POWA_EXTRA_SQL		SQL to run in the powa database after setting it up.

When PoWA is enabled on a new cluster, the image creates the powa database with PoWA's extensions, plus hypopg in the postgres and template1 databases. To set PoWA up on an existing cluster, enable powa and run docker exec <container> psql -U postgres -f /usr/local/src/install_all_powa_ext.sql.

New clusters also get wal_level = logical, 10 WAL senders and replication slots, max_locks_per_transaction = 128 (as MobilityDB recommends) and trust the logical decoding plugins shipped in the image (output_plugin_libraries).

Upgrading

Citus and DocumentDB moved to the -full images

The first 3.7 releases, from November 10, 2026, also had Citus and DocumentDB in the regular tags. They're now only in the -full tags: clusters using them must switch (18-3.7 to 18-3.7-full). Clusters created before switching lack the setting new -full clusters get for PL/Java: pljava.vmoptions = '-Djava.security.manager=allow'.

From the 3.6 images to 3.7

• Upgrade PostGIS in each database with SELECT postgis_extensions_upgrade();.
• PostGIS 3.7 no longer bundles address_standardizer and postgis_tiger_geocoder; this image installs their standalone packages, so databases using them keep working. Update them when convenient with ALTER EXTENSION address_standardizer UPDATE; (and likewise for the others).
• Nothing is preloaded by default on new clusters; existing clusters keep the libraries their configuration lists.
• The PoWA standby mode (POWA_ROLE=STANDBY) is gone: initialization now fails if it's set.

After an update that brings a new TimescaleDB version, run ALTER EXTENSION timescaledb UPDATE; as the first command of a new session (psql -X) in each database that uses it.

Background worker slots

Clusters created with images published before November 2026 set max_worker_processes = 10, fewer than the default preloaded libraries need: some of their background workers fail to start ("worker registration failed"), such as pglogical's, TimescaleDB's job schedulers and pg_partman's maintenance. New clusters get 8 plus what their libraries need. On older clusters, raise it (ALTER SYSTEM SET max_worker_processes = 20;) and restart.

Security advisory: replication trusted from any host

Clusters created with images published before November 2026 trust replication connections from any IPv4 address, without a password: the PoWA setup script appended host replication all 0.0.0.0/0 trust to pg_hba.conf. Anyone reaching the server's port can copy the whole cluster with pg_basebackup. Remove that line and reload:

docker exec <container> bash -c 'sed -i "/^host\s\+replication\s\+all\s\+0\.0\.0\.0\/0\s\+trust/d" "$PGDATA/pg_hba.conf"'
docker exec <container> psql -U postgres -c 'SELECT pg_reload_conf()'

Extensions

The extensions shipped with PostgreSQL itself (contrib) are available as well.

Extension	PostgreSQL	Preload	Notes
address_standardizer	all		Packaged separately from PostGIS since 3.7
age	all
asn1oid	all
credcheck	all	credcheck
datasketches	all
db_migrator	all
ddlx	all
decoder_raw	all		Logical decoding output plugin (SQL statements), not an extension; trusted on new clusters
decoderbufs	all		Logical decoding output plugin (Protocol Buffers, for Debezium), trusted on new clusters; its package lists it as an extension, but there's nothing to create
E-Maj	all		Without its Perl and PHP client tools
extra_window_functions	all
first_last_agg	all
h3-pg	all
hll	all
http	all
hypopg	all
icu_ext	all
index_advisor	all
ip4r	all
json_accessors	all
jsquery	all
MobilityDB	all
mongo_fdw	all
mysql_fdw	all
numeral	all
ogr_fdw	all
ora_migrator	all
oracle_fdw	all
orafce	all
parray_gin	all
periods	all
permuteseq	all
pg_auto_failover	all	pgautofailover	The monitor's extension, plus pg_autoctl. Opt-in: preloaded, it makes DROP DATABASE hang on PostgreSQL 15+ (#1063, fixed after 2.2)
pg_background	all
pg_bigm	all
pg_bulkload	all
pg_cron	all	pg_cron
pg_csv	all
pg_curl	all
pg_dirtyread	all
pg_fact_loader	up to 17
pg_graphql	all
pg_hashids	all
pg_hint_plan	all
pg_idkit	15+
pg_incremental	16+
pg_ivm	all	pg_ivm	Preloading is recommended, not required
pg_jobmon	all
pg_jsonschema	all
pg_net	all	pg_net
pg_partman	all	pg_partman_bgw	Preload only for the background maintenance worker, which runs as pg_partman_bgw.role (default partman_maintainer, a role you create)
pg_permissions	all
pg_plan_filter	all	plan_filter	A library, not an extension: set plan_filter.statement_cost_limit to reject costlier statements
pg_profile	all
pg_pwhash	all
pg_qualstats	all	pg_qualstats
pg_rational	all
pg_repack	all
pg_rewrite	all	pg_rewrite	Needs pg_rewrite in output_plugin_libraries, which new clusters get
pg_roaringbitmap	all
pg_rowalesce	all
pg_rrule	all
pg_savior	all	pg_savior	Off unless pg_savior.enabled = on when SHARED_PRELOAD_LIBRARIES adds it
pg_show_plans	all	pg_show_plans	Off by default, as it crashes inserts into TimescaleDB hypertables. pg_show_plans.is_enabled = on applies server-wide, even SET in a session (PostgreSQL 14: at server start only)
pg_similarity	all
pg_squeeze	all	pg_squeeze
pg_stat_kcache	all	pg_stat_kcache
pg_stat_log	18+	pg_stat_log
pg_stat_monitor	all	pg_stat_monitor
pg_statement_rollback	all	pg_statement_rollback	A library, not an extension: preload it, or LOAD it per session. Off unless pg_statement_rollback.enabled = on when SHARED_PRELOAD_LIBRARIES adds it
pg_statviz	all
pg_store_plans	all	pg_store_plans
pg_textsearch	17+	pg_textsearch
pg_tle	all	pg_tle
pg_track_settings	all
pg_uuidv7	all
pg_wait_sampling	all	pg_wait_sampling
pg_xenophile	all
pg_xxhash	all
pgactive	all	pgactive	Needs pgactive in output_plugin_libraries, which new clusters get. A pgactive node can't also subscribe through pglogical or built-in logical replication
pgagent	all
pgaudit	all	pgaudit
pgauditlogtofile	all	pgauditlogtofile
pgdd	all
pgextwlist	all		A library, not an extension: load it per session (session_preload_libraries) to let non-superusers create the extensions listed in extwlist.extensions
pgfaceting	all
pgfincore	all
pgl_ddl_deploy	up to 17
pglogical	all	pglogical
pglogical_ticker	up to 17	pglogical_ticker
pgmemcache	all	pgmemcache
pgmp	all
pgmq	all
pgnodemx	all	pgnodemx
pgpcre	all
pgpdf	all
pgq	all
pgq_node	all
pgrouting	all
pgsentinel	all	pgsentinel
pgsodium	all	pgsodium	Preloading enables its server-key functions (see the root key note above)
pgsphere	all
pgsql-gzip	all
pgsql_tweaks	all
pgtap	all
pgtt	all
pguint	all
pguri	all
pgvector	all
pgvectorscale	all
pgx_ulid	all
PL/JS	all
PL/Lua	all
PL/Perl	all
PL/Proxy	all
PL/PRQL	all
PL/Python	all
PL/sh	all
PL/Tcl	all
pldebugger	all	plugin_debugger
plpgsql_check	all
plProfiler	all	plprofiler	Collects nothing when plugin_debugger is loaded after it, as in the legacy and all presets: PL/pgSQL takes one plugin
pointcloud	all
PostGIS	all	postgis-3	From the base image; preloading it is optional
postgis_tiger_geocoder	all		Packaged separately from PostGIS since 3.7
postgres-protobuf	all
postgresql-debversion	all
PoWA (archivist)	all	powa	Preloading it also preloads its statistics extensions and creates the powa database on new clusters
prefix	all
prioritize	all
q3c	all
redis_fdw	all
repmgr	all	repmgr	Plus the repmgr and repmgrd commands
rum	all
semver	all
set_user	all	set_user
sqlite_fdw	up to 17
Supabase Vault	all	supabase_vault	Needs preloading (see the root key note above)
table_log	all
tdigest	all
tds_fdw	all
temporal_tables	all
timescaledb	all	timescaledb	Includes the Timescale License (TSL) features
TimescaleDB Toolkit	15+		Timescale License (TSL)
timestamp9	all
toastinfo	all
TopN	all
unit	all
VectorChord	all	vchord	Dual-licensed AGPLv3 / ELv2
wal2json	all		Logical decoding output plugin, not an extension

Only in the -full images

Extension	PostgreSQL	Preload	Notes
Citus	all	citus	Opt-in; loaded before every other library, as Citus requires. PostgreSQL 14 gets Citus 12.1 and 15 gets 13
DocumentDB	15+	pg_documentdb	Opt-in. SQL API only (no MongoDB wire-protocol gateway); documentdb_distributed also needs Citus preloaded
pg_duckdb	all	pg_duckdb	Opt-in. DuckDB downloads extensions (httpfs, iceberg...) on first use unless duckdb.autoinstall_known_extensions is off
pg_parquet	all	pg_parquet	Opt-in. Preloaded with pg_duckdb, it handles COPY ... (format 'parquet')
pg_search	15+	pg_search	Opt-in. Its bm25 access method clashes with pg_textsearch's: don't create both in one database
pg_vectorize	all	vectorize	Opt-in. Create it in pg_cron's database, where its worker connects as postgres (see vectorize.host); embeddings come from an external service
PGroonga	all		Built with Debian's Groonga, without the MeCab tokenizer
PL/Java	all		Java 21 needs pljava.vmoptions to choose the security manager mode: new clusters set -Djava.security.manager=allow
PL/R	all
RDKit	all
Supabase Wrappers	all		Foreign data wrappers for S3, Iceberg, DuckDB, BigQuery, ClickHouse, Stripe, Airtable and more, plus Wasm ones

Development

The images are built with Docker Bake and tested with pytest and pgTAP:

docker buildx bake pg18 --load --set pg18.tags=postgis-with-extensions:dev   # pg18-full for the -full image
uv run pytest --image postgis-with-extensions:dev
uv run prek run --all-files                                                 # linters and formatters

Set PWE_TEST_LOGS to a directory to keep the output of every server the tests start; CI uploads it as an artifact.

These and other tasks (dispatching CI, reading its logs) are also just recipes: run just to list them. Install just with your package manager (scoop install just, brew install just, ...) or uv tool install rust-just.

To add an extension:

• Install it: add its PGDG package to build/apt-packages.txt; a PGXS source to build/pgxn-packages.txt (PGXN) or build/github-packages.txt (GitHub); an upstream binary to build/fetch-vendor.sh; or a build stage to the Dockerfile. Pin everything but PGDG packages (with a # renovate: comment in the Dockerfile).
• Heavy or niche extensions go in the -full images only: build/apt-packages-extended.txt, build/fetch-vendor-extended.sh, build/build-pgrx.sh (pgrx sources) or a stage copied into the extended one.
• Describe it in extensions.toml (with extended = true for the -full images) and run uv run python -m scripts.render_readme to update the tables.
• If it needs preloading, register its library in image/preload-libraries.txt, with the background workers it starts.
• If it ships a logical decoding output plugin, add it to trusted_plugins in image/initdb/z_conf.sh.
• Add tests/sql/<extension>.sql, a pgTAP script proving the extension works (known answers, not just loading), marked -- image: extended for the -full images.

CI builds and tests every PostgreSQL major on each pull request, and publishes from master and the weekly scheduled run. Renovate keeps the pinned versions current on Sundays; the Monday scheduled run publishes its updates.

License

MIT