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/endindexes) -- recurrence expansion at query time via rrule_plpgsql, no C extensions needed - Extensible via
IPGIndexTranslatornamed utilities for custom index types - Dynamic index discovery from ZCatalog at startup -- addons adding indexes via
catalog.xmljust 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_tokenizerextensions are detected, search results are automatically ranked using BM25 (IDF, term saturation, length normalization) instead ofts_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:17Docker images; for BM25 usetensorchord/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:defaultGenericSetup profile -- either through the Plone Add-on control panel or programmatically:setup = portal.portal_setup setup.runAllImportStepsFromProfile("profile-plone.pgcatalog:default")
This replaces
portal_catalogwithPlonePGCatalogTool, 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
Release files for plone.pgcatalog 1.0.0rc1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| plone_pgcatalog-1.0.0rc1.tar.gz | 1.7 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| plone_pgcatalog-1.0.0rc1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.9 MB
Release files / plone_pgcatalog-1.0.0rc1.tar.gz
| Download URL | plone_pgcatalog-1.0.0rc1.tar.gz |
|---|---|
| Size | 1.7 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc6051c4ce19ae45eb76f0af5b599de23550b92970c9f7917688553dfca7e836
|
|
BLAKE2b-256 checksum How to use checksums |
88e2b578d0e9d9d24c45a0eb85a69ca9f191005da35de60f31929e981a631619
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency logRelease files / plone_pgcatalog-1.0.0rc1-py3-none-any.whl
| Download URL | plone_pgcatalog-1.0.0rc1-py3-none-any.whl |
|---|---|
| Size | 184.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
511c3350c89c9759b14b6a9146847a6b699d17eb2b54d2ea73ea383df6c6021a
|
|
BLAKE2b-256 checksum How to use checksums |
df303c5515d42d36d2c758d450e9f3e9ec91c07aa93d3b9b966a7b3b9c931c23
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 15, 2026.
Transparency log
