Home

Welcome to the eventferry wiki — a transactional outbox toolkit for Postgres / MySQL with a hardened Kafka / Redpanda publisher.

eventferry guarantees that every domain event written inside your business transaction reaches the broker exactly once, in the order your aggregate produced it, even when the broker is down, the relay process crashes, or a deploy rolls every replica at once. No dual-writes, no message loss, no out-of-order delivery on a per-aggregate basis.

---

At a glance

Surface	What it gives you
Stores	PostgresStore (16+), MysqlStore (8+) — atomic enqueue inside your existing transaction, SKIP LOCKED batch claim, server-side TZ-safe reaper
Relays	Polling Relay, low-latency PostgresStreamingRelay (logical replication), PostgresNotifyWaker (LISTEN/NOTIFY), MySQL binlog relay
Publisher	KafkaPublisher with kafkajs + @confluentinc/kafka-javascript drivers, idempotent + transactional EOS, DLQ enrichment, fenced-restart, health checks
Schemas	Confluent Schema Registry serializer — Avro / Protobuf / JSON Schema, subject naming strategies, key serialization, basic / bearer auth
Type safety	defineOutbox(registry) — same Standard Schema registry on both sides; producer validates on enqueue, consumer validates on decode
Tracing	W3C trace context propagation end-to-end via tracer.inject + extractTraceContext — your OTel consumer span becomes a child of the producer span

---

Why a wiki?

The README focuses on quick start + what's possible. This wiki is the long-form home for:

• Architecture deep-dives (how the relay claims rows, how strict ordering survives concurrent claimers)
• Production playbooks (scaling many relays, retention, monitoring)
• Surface-by-surface configuration (every knob, every default, why)
• Troubleshooting recipes from real incidents
• API reference for every public export

---

Table of contents

Get going

• Getting Started — install + 30-second demo
• Core Concepts — outbox pattern, relay, store, publisher
• Packages — what each @eventferry/* package does and when to pull it in

Adapters

• Postgres Adapter
• MySQL Adapter
• Kafka Publisher

Type & schema

• Type-Safe Events — defineOutbox(registry)
• Schema Registry — Avro / Protobuf / JSON Schema

Security & connection

• Authentication and TLS — mTLS, SASL/PLAIN, SCRAM, OAUTHBEARER, dev-cluster recipes
• AWS MSK IAM — @eventferry/kafka-iam helper

Operational features

• Transactions and EOS — idempotent vs transactional, fenced-restart, multi-instance strategy
• Admin Operations — publisher.admin(), ensureTopics, validateTopicsOnConnect
• Observability — OTel tracing, hooks, librdkafka stats, health checks
• Consuming Events — decode, extractTraceContext, typed payload via registry
• Dead-Letter Queue — enriched headers, routing recipe
• Reliability and Error Handling — errorKind taxonomy, backpressure, quota

Operations

• Operations Guide — production checklist, scaling, retention, monitoring
• Migrations and Upgrades
• Troubleshooting

Reference

• API Reference
• FAQ
• Roadmap

---

Versions

Package	Latest
@eventferry/core	3.4.0
@eventferry/postgres	3.3.2
@eventferry/mysql	3.3.2
@eventferry/kafka	3.5.0
@eventferry/schema-registry	3.4.0
@eventferry/kafka-iam	0.2.1
@eventferry/all (meta)	3.2.5

Each package follows independent SemVer. The all meta-package re-exports the core + DB + Kafka + Schema Registry surfaces — install it if you don't want to manage individual packages.

---

Project links

• Repository — https://github.com/SametGoktepe/eventferry
• Issues — https://github.com/SametGoktepe/eventferry/issues
• Changelogs — each package ships its own CHANGELOG.md in the npm tarball
• License — MIT