Skip to main content

Postgres and Redis

Run one server and several workers on a shared Postgres store and Redis broker.

Prerequisites​

  • the afe-postgres and afe-redis plugins installed.
  • Docker, to run Postgres and Redis locally with docker/compose.yml.

Steps​

  1. Name a store and a broker in a Runtime manifest.

    One afe serve process and several afe worker processes then share the same tickets safely. The per-ticket lock and the write-ahead store keep two workers from repeating work.

  2. Start Postgres and Redis for local runs with docker/compose.yml.

    It runs Postgres 17 on 127.0.0.1:5434 and Redis 8 on 127.0.0.1:6381. The same services serve local runs, make integration and make e2e. Stop them with make down, which also stops Langfuse, the OpenTelemetry Collector and the kind cluster when they run.

  3. Start one afe serve and several afe worker processes against that store and broker.

Migrations​

The Postgres plugin ships numbered SQL migrations.

At startup it takes a Postgres advisory lock, creates a schema_version table and applies every migration above the recorded version, one transaction each. Two processes starting together apply each migration once. A database already at the latest version is left untouched.

Troubleshooting​

Symptom: afe serve or afe worker fails to connect, with a connection refused error. Cause: Postgres or Redis are not running, or AFE_POSTGRES_DSN and AFE_REDIS_URL point at the wrong host and port. Fix: start the services with docker compose -f docker/compose.yml up -d --wait, then check both variables against the ports above.

Symptom: two processes start together and one logs a migration error. Cause: this should not happen. The advisory lock serializes migrations across processes. Fix: report it, with the full error, as a defect: it points at a broken migration or a lock that did not hold.

See also​