Configuration reference¶

This page documents all configuration options for plone.pgcatalog, including Zope configuration, environment variables, GenericSetup profiles, and dependency information.

zope.conf settings¶

plone.pgcatalog requires zodb-pgjsonb as its ZODB storage backend. The storage is configured in zope.conf:

%import zodb_pgjsonb

<zodb_db main>
  <pgjsonb>
    dsn dbname=zodb host=localhost port=5432 user=zodb password=zodb
  </pgjsonb>
</zodb_db>

Using environment variables in zope.conf¶

ZConfig supports variable substitution via the %define directive and the ${} syntax. Combined with environment variables, this keeps secrets out of the configuration file:

%import zodb_pgjsonb

<zodb_db main>
  <pgjsonb>
    dsn dbname=${ZODB_DB:zodb} host=${ZODB_HOST:localhost} port=${ZODB_PORT:5432} user=${ZODB_USER:zodb} password=${ZODB_PASSWORD:zodb}
    blob-dir ${ZODB_BLOB_DIR:/var/plone/blobs}
  </pgjsonb>
</zodb_db>

The ${VAR:default} syntax falls back to the value after the colon when the environment variable is not set. This works for any ZConfig directive, not just dsn. See the ZConfig documentation for details.

plone.pgcatalog itself is autodiscovered via z3c.autoinclude and does not need a separate %import directive.

Environment variables¶

Variable	Default	Description
`PGCATALOG_BM25_LANGUAGES`	(none)	Comma-separated ISO 639-1 codes, or `"auto"` to detect from `portal_languages`. Controls which per-language BM25 columns are created. Only relevant when VectorChord-BM25 extensions are installed.
`PGCATALOG_TIKA_URL`	(none)	Tika server URL, for example `http://localhost:9998`. Enables async text extraction from binary content (PDFs, Office docs, images). When set, the queue table and merge function are created at startup. See Enable Tika text extraction.
`PGCATALOG_TIKA_CONTENT_TYPES`	common office/PDF/image types	Comma-separated MIME types to send to Tika. Default includes PDF, MS Office, OpenDocument, RTF, and common image formats.
`PGCATALOG_TIKA_INPROCESS`	(none)	Set to `true`, `1`, or `yes` to start the extraction worker as a daemon thread inside the Zope process. Requires `PGCATALOG_TIKA_URL`.
`PGCATALOG_SLOW_QUERY_MS`	`10`	Threshold in milliseconds for slow query detection. Queries exceeding this are logged as warnings and recorded in the `pgcatalog_slow_queries` table for analysis via the ZMI Slow Queries tab. Set to `0` to disable.
`PGCATALOG_QUERY_CACHE_SIZE`	`200`	Max cached query results per process. Set to `0` to disable. Invalidated when `pgcatalog_change_seq` changes (only on catalog writes, not on unrelated ZODB commits). Cost-based eviction keeps expensive queries in cache.
`PGCATALOG_QUERY_CACHE_TTR`	`60`	Time-to-round in seconds for datetime values in cache keys. Controls cache key granularity for effectiveRange queries. Higher values = more cache hits but slightly stale effectiveRange.
`PGCATALOG_PREFETCH_BATCH`	`100`	Number of objects to prefetch when `brain.getObject()` is called. Set to `0` to disable. Requires zodb-pgjsonb >= 1.8.0. In addition, automatic refs prefetch on `load()` is registered at startup when zodb-pgjsonb >= 1.9.2 is available (uses `idx IS NOT NULL` filter to limit prefetch to cataloged content).
`ZODB_TEST_DSN`	`dbname=zodb_test host=localhost port=5433 user=zodb password=zodb`	DSN for test database (tests only).
`BM25_TEST_DSN`	`dbname=zodb_test host=localhost port=5434 user=zodb password=zodb`	DSN for BM25 integration tests (tests only).

Standalone worker environment variables¶

These variables configure the pgcatalog-tika-worker CLI when running as a standalone process (outside Zope):

Variable	Default	Description
`TIKA_WORKER_DSN`	(required)	PostgreSQL connection string.
`TIKA_WORKER_URL`	(required)	Tika server URL.
`TIKA_WORKER_POLL_INTERVAL`	`5`	Seconds between polls when idle (LISTEN/NOTIFY provides instant wakeup).
`TIKA_WORKER_S3_BUCKET`	(none)	S3 bucket name for S3-tiered blobs.
`TIKA_WORKER_S3_ENDPOINT_URL`	(none)	S3 endpoint URL (for MinIO or compatible).
`TIKA_WORKER_S3_REGION`	(none)	S3 region name.

GenericSetup profile¶

plone.pgcatalog ships a GenericSetup profile (default) that configures Plone to use the PostgreSQL-backed catalog.

setuphandlers.py: Replaces portal_catalog with PlonePGCatalogTool, preserving addon index definitions via automatic snapshot and restore.
metadata.xml: Profile version 1.

The profile is applied automatically when installing the add-on through the Plone control panel or via a dependency declaration in another profile.

ZCML registration¶

All ZCML registrations are loaded automatically via z3c.autoinclude. The following registrations are made:

PlonePGCatalogTool registered as IPGCatalogTool utility.
IDatabaseOpenedWithRoot subscriber for startup initialization (schema creation, index registry sync, connection pool setup).
IPubEnd subscriber that releases request-scoped PostgreSQL connections at the end of each HTTP request.

Python dependencies¶

Package	Purpose
`psycopg[binary,pool]>=3.1`	PostgreSQL adapter with connection pooling.
`orjson>=3.9`	Fast JSONB deserialization.
`Products.CMFPlone`	Plone framework.
`zodb-pgjsonb>=1.8`	ZODB storage backend (provides the `object_state` table). v1.8.0 adds `load_multiple()` for batch prefetch; v1.9.2 adds `register_prefetch_refs_expr()` for automatic refs prefetch on `load()`.

Optional dependencies¶

Package	Extra	Purpose
VectorChord-BM25 (`vchord_bm25`)	—	BM25 ranking extension for PostgreSQL. Enables relevance-ranked full-text search as an alternative to tsvector ranking.
pg_tokenizer	—	Text tokenization for BM25 (language-specific stemmers and vocabulary mapping).
`httpx>=0.24`	`tika`	HTTP client for Tika communication. Required for text extraction.
`boto3>=1.26`	`tika-s3`	AWS SDK for S3-tiered blob access. Only needed when blobs are stored in S3.

Install extras with: pip install plone.pgcatalog[tika] or pip install plone.pgcatalog[tika-s3].

Console scripts¶

Command	Description
`pgcatalog-tika-worker`	Standalone text extraction worker. Requires `TIKA_WORKER_DSN` and `TIKA_WORKER_URL` environment variables. See Enable Tika text extraction.

Docker images¶

Image	Use Case
`postgres:17`	Standard PostgreSQL with tsvector-based full-text ranking.
`tensorchord/vchord-suite:pg17-latest`	PostgreSQL with VectorChord-BM25 and pg_tokenizer pre-installed.
`apache/tika:latest`	Apache Tika server for text extraction from PDFs, Office docs, and images. Stateless, no persistent storage needed.

PostgreSQL tuning recommendations¶

For SSD-based deployments (most modern setups), set random_page_cost = 1.1 in postgresql.conf (default is 4.0, tuned for spinning disks). This helps the planner prefer index scans over bitmap scans for complex multi-field queries. Verified on production: ~2x improvement for navigation queries without affecting simple queries.

For large Plone sites, configure the ZODB cache generously:

<zodb_db main>
  cache-size 70000
  cache-size-bytes 500MB
  <pgjsonb>
    dsn ...
  </pgjsonb>
</zodb_db>

The default ZODB cache (5000 objects) is too small for sites with many content objects. A site with 14,000 events showed 5-6 second warm-cache page loads with the default, dropping to 0.8 seconds with 70,000 objects.