Configure PGJsonb storage#

This guide walks you through setting up PGJsonb as your ZODB storage backend. PGJsonb stores object state as PostgreSQL JSONB, making it queryable with standard SQL operators.

Prerequisites#

  • New to this template? Start with Your first Zope instance.

  • A running PostgreSQL 14+ server

  • The zodb-pgjsonb and zodb-json-codec Python packages installed

  • A PostgreSQL database created for your Zope instance

Step 1: set the storage type#

In your instance.yaml, set the storage backend to pgjsonb:

default_context:
    db_storage: pgjsonb

Step 2: configure the connection string#

Provide the PostgreSQL DSN so the storage can connect to your database:

default_context:
    db_storage: pgjsonb
    db_pgjsonb_dsn: "dbname='zodb' user='zodb' host='localhost' port='5433'"

URI format is also supported:

default_context:
    db_pgjsonb_dsn: "postgresql://zodb:zodb@localhost:5433/zodb"

Step 3: choose history mode#

By default, PGJsonb uses a history-free schema (no undo, better performance). To enable ZODB-level undo support:

default_context:
    db_storage: pgjsonb
    db_pgjsonb_dsn: "dbname='zodb' user='zodb' host='localhost' port='5433'"
    db_pgjsonb_history_preserving: true

Complete example#

default_context:
    # Serving (bind to localhost when behind a reverse proxy)
    wsgi_listen: 127.0.0.1:8080

    initial_user_name: admin
    initial_user_password: admin

    zcml_package_includes: my.awesome.addon

    # PGJsonb storage
    db_storage: pgjsonb
    db_pgjsonb_dsn: "dbname='zodb' user='zodb' host='db' port='5432'"
    db_pgjsonb_history_preserving: false

    # ZODB object cache
    db_cache_size: 50000

For the full set of annotated sample configurations, including development and other backend variants, see Sample configurations.

Optional: S3 tiered blob storage#

For deployments with many large blobs, you can tier blobs to S3-compatible object storage:

default_context:
    db_storage: pgjsonb
    db_pgjsonb_dsn: "dbname='zodb' user='zodb' host='db' port='5432'"
    db_pgjsonb_s3_bucket_name: my-zodb-blobs
    db_pgjsonb_s3_endpoint_url: "http://minio:9000"
    db_pgjsonb_s3_region: us-east-1
    db_pgjsonb_s3_access_key: minio-access-key
    db_pgjsonb_s3_secret_key: minio-secret-key
    db_pgjsonb_blob_threshold: 100KB
    db_pgjsonb_blob_cache_dir: /var/cache/zodb-blobs
    db_pgjsonb_blob_cache_size: 2GB

Blobs smaller than db_pgjsonb_blob_threshold remain in PostgreSQL bytea. Set the threshold to 0 to send all blobs to S3.

Important: blob settings not used with PGJsonb#

The generic blob settings db_blob_mode and db_blob_location are not used with PGJsonb. PGJsonb manages blob storage through its own settings (db_pgjsonb_blob_* and db_pgjsonb_s3_*).

Next steps#