Configure RelStorage with PostgreSQL

This guide walks you through setting up RelStorage with PostgreSQL as your ZODB storage backend. RelStorage stores pickles in a relational database and is the recommended backend for production Plone deployments that need horizontal scaling.

Prerequisites

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

  • A running PostgreSQL server

  • The RelStorage and psycopg2 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 relstorage:

default_context:
    db_storage: relstorage

Step 2: set the blob mode

RelStorage stores blobs in the database. Your Zope client needs a local cache directory for blob data. Set the blob mode to cache:

default_context:
    db_storage: relstorage
    db_blob_mode: cache

Important

You must set db_blob_mode to cache when using RelStorage. The default value shared is only appropriate for direct filestorage.

Step 3: choose the database backend

Set the relational database type. PostgreSQL is the recommended choice:

default_context:
    db_storage: relstorage
    db_blob_mode: cache
    db_relstorage: postgresql

Other supported values are mysql, oracle, and sqlite3.

Step 4: configure the connection string

Provide the PostgreSQL DSN (Data Source Name) so RelStorage can connect to your database:

default_context:
    db_storage: relstorage
    db_blob_mode: cache
    db_relstorage: postgresql
    db_relstorage_postgresql_dsn: "host='localhost' dbname='plone' user='plone' password='secret'"

Complete example

Here is a complete, runnable instance.yaml with commonly tuned settings:

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

    # Storage
    db_storage: relstorage
    db_blob_mode: cache
    db_relstorage: postgresql
    db_relstorage_postgresql_dsn: "host='db' dbname='plone' user='plone' password='secret'"

    # Performance tuning
    db_cache_size: 50000
    db_cache_size_bytes: 1500MB
    db_relstorage_keep_history: false

    # Blob cache
    db_blob_cache_size: 10737418240  # 10 GB

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

Generated helper files

When you use RelStorage, the cookiecutter also generates configuration files for RelStorage command-line utilities:

  • relstorage-pack.conf – Always generated. Used with the zodbpack command for database packing and garbage collection.

  • relstorage-export.conf – Generated when db_relstorage_export_* settings are provided. Used with zodbconvert to export data to a filestorage.

  • relstorage-import.conf – Generated when db_relstorage_import_* settings are provided. Used with zodbconvert to import data from a filestorage.

Tip

For migrating data between storage backends, the generic zodb-convert tool is now the recommended approach. It works with all storage backends and can read storage configuration directly from zope.conf files. See Migrate data between storage backends for a step-by-step guide.

Next steps