Skip to main content

Data Storage

Releval persists three categories of state:

  • Application data — endpoints, evaluations, judgments, members, and everything else modelled in the API. Stored in PostgreSQL.
  • User behaviour events — high-volume click and impression streams powering the User Behaviour Insights Workspace. Stored in ClickHouse.
  • Uploaded files — query sets, judgment lists, and analysis inputs. Stored on local disk by default, or in AWS S3.

An optional Redis instance provides a distributed cache and real-time messaging backplane. It is required for multi-container deployments.

PostgreSQL​

PostgreSQL stores all application data for Releval, and is configured with a connection string.

VariableDefault
ConnectionStrings__Postgres(none)

Example​

environment:
  - ConnectionStrings__Postgres=Host=<hostname>;Port=<port>;Database=<database>;Username=<user>;Password=<password>

ClickHouse​

ClickHouse is an OLAP analytical database used to store user behaviour insights (UBI) events and queries.

VariableDefault
ConnectionStrings__ClickHouse(none)
environment:
  - ConnectionStrings__ClickHouse=Host=<hostname>;Port=<port>;Database=<database>;Username=<user>;Password=<password>;Compression=<true|false>

Least-privilege user​

Releval only reads from and writes to two tables in the configured database: ubi_events and ubi_queries. The connection string should use a dedicated ClickHouse user whose privileges are scoped to those two tables — that way an exposed credential cannot reach anything else in the cluster, and the Workspace is naturally limited to UBI data.

Create the user from a ClickHouse admin session:

-- Replace with a strong password generated by your secrets manager.
CREATE USER releval IDENTIFIED WITH sha256_password BY 'replace-with-strong-password';

-- Dedicated database for UBI data. Use the same name in
-- ConnectionStrings__ClickHouse (Database=releval).
CREATE DATABASE IF NOT EXISTS releval;

-- Bootstrap: Releval creates ubi_events and ubi_queries on first run.
GRANT CREATE TABLE ON releval.* TO releval;

-- Steady state: read and write only the two UBI tables.
GRANT SELECT, INSERT, SHOW ON releval.ubi_events TO releval;
GRANT SELECT, INSERT, SHOW ON releval.ubi_queries TO releval;

After the first successful Releval startup the two tables exist; if you want to tighten further you can either leave the CREATE TABLE grant in place (harmless once the tables exist) or pre-create the tables yourself and revoke the grant — Releval will not try to recreate them.

The user has no access to other databases or to any other table in the releval database, so Workspace queries can only join across ubi_events and ubi_queries.

ClickHouse Keeper​

ClickHouse does not strictly require ClickHouse Keeper for a single-node, non-replicated setup. However, ClickHouse Keeper is required for data replication, high availability, and distributed cluster coordination.

In the Getting Started Docker Compose example, this is provided by the clickhouse-keeper service.

File storage​

Uploaded files default to local disk and can be redirected to S3 by setting a bucket name. The first matching configuration wins — if FileStorage__Aws__BucketName is set, S3 is used; otherwise the local provider runs.

Local disk (default)​

VariableDefaultDescription
FileStorage__Local__Directory/app/filesDirectory path for file uploads

In Docker deployments, mount a volume to persist files across container restarts:

services:
  releval:
    volumes:
      - releval-files:/app/files

volumes:
  releval-files:

AWS S3​

To store files in S3, set the bucket name. Releval automatically switches to the S3 provider when a bucket is configured.

VariableDefaultDescription
FileStorage__Aws__BucketName(none)S3 bucket name (enables S3 storage)
FileStorage__Aws__Region(none)AWS region
FileStorage__Aws__KeyPrefix(none)Prefix for all object keys in the bucket
FileStorage__Aws__AccessKeyId(none)AWS access key (optional if using IAM roles)
FileStorage__Aws__SecretAccessKey(none)AWS secret key (optional if using IAM roles)

With IAM credentials​

environment:
  - FileStorage__Aws__BucketName=my-releval-bucket
  - FileStorage__Aws__Region=us-west-2
  - FileStorage__Aws__KeyPrefix=uploads/
  - FileStorage__Aws__AccessKeyId=AKIAIOSFODNN7EXAMPLE
  - FileStorage__Aws__SecretAccessKey=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

With IAM roles​

When running on AWS (EC2, ECS, EKS), use IAM instance profiles or task roles instead of explicit credentials:

environment:
  - FileStorage__Aws__BucketName=my-releval-bucket
  - FileStorage__Aws__Region=us-west-2

Redis (optional)​

VariableDefault
ConnectionStrings__Redis(none)

When Redis is configured, Releval uses it for:

  • Distributed cache — shared L2 cache across application instances with automatic cache invalidation.
  • Real-time messaging backplane — broadcasts notifications (evaluation progress, task updates) to clients connected to any instance.

Without Redis, caching and real-time messaging are handled in-process, which works for single-instance deployments but means clients only receive notifications from the instance they are connected to.

Example​

environment:
  - ConnectionStrings__Redis=redis:6379
Info

Redis is required for multi-container deployments where multiple Releval instances run behind a load balancer. Without it, each instance maintains its own cache and can only deliver real-time notifications to directly connected clients.