Pre-release

This release is a pre-release and may not be stable for production use.

plone.pgcatalog

PostgreSQL-backed catalog for Plone, replacing ZCatalog BTrees indexes with SQL queries on JSONB.

Requires zodb-pgjsonb as the ZODB storage backend.

Features

All standard index types supported: FieldIndex, KeywordIndex, DateIndex, BooleanIndex, DateRangeIndex, UUIDIndex, ZCTextIndex, ExtendedPathIndex, GopipIndex
DateRecurringIndex for recurring events (Plone's start/end indexes) -- recurrence expansion at query time via rrule_plpgsql, no C extensions needed
Extensible via IPGIndexTranslator named utilities for custom index types
Dynamic index discovery from ZCatalog at startup -- addons adding indexes via catalog.xml just work
Transactional writes -- catalog data written atomically alongside object state during ZODB commit
Full-text search via PostgreSQL tsvector/tsquery -- language-aware stemming for SearchableText (30 languages), word-level matching for Title/Description/addon ZCTextIndex fields
Optional BM25 ranking -- when vchord_bm25 + pg_tokenizer extensions are detected, search results are automatically ranked using BM25 (IDF, term saturation, length normalization) instead of ts_rank_cd. Title matches are boosted. Falls back to tsvector ranking on vanilla PostgreSQL.
Zero ZODB cache pressure -- no BTree/Bucket objects stored in ZODB
Container-friendly -- works on standard postgres:17 Docker images; for BM25 use tensorchord/vchord-suite:pg17-latest

Requirements

Python 3.12+
PostgreSQL 15+ (tested with 17)
zodb-pgjsonb
Plone 6

Installation

pip install plone-pgcatalog

Add to your Zope configuration:

<!-- zope.conf -->
%import zodb_pgjsonb
<zodb_main>
  <pgjsonb>
    dsn dbname=mydb user=zodb password=zodb host=localhost port=5432
  </pgjsonb>
</zodb_main>

Install the plone.pgcatalog:default GenericSetup profile through Plone's Add-on installer or your policy package.

Usage

Once installed, portal_catalog is replaced with PlonePGCatalogTool. All catalog queries use the same ZCatalog API:

# Standard catalog queries -- same syntax as ZCatalog
results = catalog(portal_type="Document", review_state="published")
results = catalog(Subject={"query": ["Python", "Plone"], "operator": "or"})
results = catalog(SearchableText="my search term")
results = catalog(SearchableText="Katzen", Language="de")  # language-aware stemming
results = catalog(Title="quick fox")  # word-level match (finds "The Quick Brown Fox")
results = catalog(path={"query": "/plone/folder", "depth": 1})

# Recurring events (DateRecurringIndex)
results = catalog(
    start={
        "query": [DateTime("2025-03-01"), DateTime("2025-03-31")],
        "range": "min:max",
    }
)

Migrating an Existing Site

If you have a running Plone site and want to switch from ZCatalog to plone.pgcatalog:

Prerequisites: Your site must already be running on zodb-pgjsonb. If you're migrating from FileStorage or RelStorage, use zodb-convert first.

Steps:

Install plone-pgcatalog into your Python environment:
```
pip install plone-pgcatalog
```
Restart Zope (plone.pgcatalog is auto-discovered via z3c.autoinclude).
Install the plone.pgcatalog:default GenericSetup profile -- either through the Plone Add-on control panel or programmatically:
```
setup = portal.portal_setup
setup.runAllImportStepsFromProfile("profile-plone.pgcatalog:default")
```
This replaces portal_catalog with PlonePGCatalogTool, preserving any addon-provided index definitions.
Rebuild the catalog to populate PostgreSQL with all existing content:
```
catalog = portal.portal_catalog
catalog.clearFindAndRebuild()
```
For a site with ~1000 documents, this takes about 15 seconds.

An automated migration script is included in example/scripts/migrate_to_pgcatalog.py that performs all steps and verifies the result.

Using with plone.distribution

An example distribution package is included in example/pgcatalog-example-distribution/. It registers a "Plone Site (PG Catalog)" distribution that appears in the site creation UI and automatically applies the plone.pgcatalog:default profile.

To use plone.pgcatalog in your own distribution, add it to profiles.json:

{
  "base": [
    "plone.app.contenttypes:default",
    "plonetheme.barceloneta:default",
    "plone.pgcatalog:default"
  ]
}

Documentation

Rendered documentation: https://bluedynamics.github.io/plone-pgcatalog/

Architecture -- design, index registry, query translation
BENCHMARKS.md -- performance comparison vs RelStorage+ZCatalog
CHANGES.md -- changelog
example/ -- runnable example with multilingual content and an example distribution

Source Code and Contributions

The source code is managed in a Git repository, with its main branches hosted on GitHub. Issues can be reported there too.

We'd be happy to see many forks and pull requests to make this package even better. We welcome AI-assisted contributions, but expect every contributor to fully understand and be able to explain the code they submit. Please don't send bulk auto-generated pull requests.

Maintainers are Jens Klein and the BlueDynamics Alliance developer team. We appreciate any contribution and if a release on PyPI is needed, please just contact one of us. We also offer commercial support if any training, coaching, integration or adaptations are needed.

License

GPL-2.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

plone_pgcatalog-1.0.0rc1.tar.gz (1.7 MB view details)

Uploaded Sep 15, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

plone_pgcatalog-1.0.0rc1-py3-none-any.whl (184.3 kB view details)

Uploaded Sep 15, 2026 Python 3

File details

Details for the file plone_pgcatalog-1.0.0rc1.tar.gz.

File metadata

Download URL: plone_pgcatalog-1.0.0rc1.tar.gz
Upload date: Sep 15, 2026
Size: 1.7 MB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for plone_pgcatalog-1.0.0rc1.tar.gz
Algorithm	Hash digest
SHA256	`cc6051c4ce19ae45eb76f0af5b599de23550b92970c9f7917688553dfca7e836`
MD5	`9db77992a20461f36c2c5ba8955fdb5f`
BLAKE2b-256	`88e2b578d0e9d9d24c45a0eb85a69ca9f191005da35de60f31929e981a631619`

See more details on using hashes here.

Provenance

The following attestation bundles were made for plone_pgcatalog-1.0.0rc1.tar.gz:

Publisher: release.yaml on bluedynamics/plone-pgcatalog

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: plone_pgcatalog-1.0.0rc1.tar.gz
- Subject digest: cc6051c4ce19ae45eb76f0af5b599de23550b92970c9f7917688553dfca7e836
- Sigstore transparency entry: 2846116009
- Sigstore integration time: Sep 15, 2026
Source repository:
- Permalink: bluedynamics/plone-pgcatalog@570afd98b68097552bf786dc785700297826f38f
- Branch / Tag: refs/tags/v1.0.0rc1
- Owner: https://github.com/bluedynamics
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yaml@570afd98b68097552bf786dc785700297826f38f
- Trigger Event: release