Mammoth Documentation

🦣 Mammoth is a self-hosted PostgreSQL TransactionEnvelope-driven Change Data Capture relay focused on reliable delivery of database change events to webhook destinations.

This documentation covers Mammoth Data Plane, the open-source runtime in the Mammoth ecosystem. See Mammoth Brand for the ecosystem naming hierarchy.

PostgreSQL
    ↓
pgoutput-client
    ↓
pgoutput-source-adapter
    ↓
CDC::Core::ChangeEvent / TransactionEnvelope
    ↓
Mammoth Data Plane
    ↓
Webhook fanout

Mammoth is intentionally boring infrastructure. It uses YAML configuration, JSON Schema validation, SQLite-backed operational memory, retries, checkpoints, and dead letters so operators can inspect and recover delivery state.

The source adapter owns incremental PostgreSQL transaction normalization. Mammoth consumes exact CDC-core work items and does not rebuild transaction envelopes inside its PostgreSQL composition layer. Persisted sample JSON crosses an explicit deserialization boundary that reconstructs exact core work before first delivery. Dead-letter replay instead sends the exact destination payload already persisted after policy projection; it does not reconstruct CDC work or reapply the current policy.

Supported PostgreSQL versions

Mammoth supports PostgreSQL 14 through PostgreSQL 18, inclusive. These are the PostgreSQL major versions currently maintained by the PostgreSQL community and covered by Mammoth's real logical-replication E2E compatibility matrix.

Mammoth supports PostgreSQL major versions that are both maintained by the PostgreSQL community and included in Mammoth's compatibility test matrix. New PostgreSQL majors are unsupported until explicitly tested and documented. EOL versions may be removed from the supported range in a subsequent Mammoth minor release with release-note notice.

PostgreSQL 19 is a development release and is not supported.

Start here

• Webhooks Quick Start
• Quick Start
• Webhook Payloads
• Payload Policies
• PostgreSQL
• Configuration
• CLI
• Benchmarks
• Operational State
• Operational-State Adapters
• Destination Adapters
• Runtime Adapters
• Observability
• Extensions
• Ecosystem
• Examples
• Compatibility
• Helm
• Diagrams
• Design System
• Iconography
• Glossary
• Troubleshooting

The Webhooks Quick Start is the recommended first-run experience. One Docker Compose command starts a demo application, PostgreSQL, Mammoth, and an inspectable signed webhook receiver with visible retries and customer-email masking. Its optional monitoring profile adds seeded traffic, a provisioned Grafana overview and alerts, and a curated Prometheus query library. See Observability for the runnable monitoring showcase. Use the documentation Quick Start when you are ready to assemble those pieces manually.

Released tags use their matching image; when testing Unreleased quickstart configuration from main, build the local image as described in the quickstart README. For measured projection, delivery, SQLite operational-state, observability, and replay costs, see Benchmarks.

v1 Release Scope

Mammoth 1.x supports:

• PostgreSQL logical replication ingestion
• normalized CDC event and transaction delivery to webhooks
• multi-destination webhook fanout
• fanout route filters by schema, table, and operation
• per-destination payload removal and masking policies
• per-destination enable/disable and retry policy controls
• transaction envelope preservation
• concurrent downstream delivery with one PostgreSQL replication stream
• retry handling
• configurable structured JSON logging to standard output
• contiguous durable-delivery watermark and PostgreSQL acknowledgement
• source-owned transport LSN preservation independent of payload commit_lsn
• fail-closed PostgreSQL slot and checkpoint continuity preflight
• publication replica-identity preflight for UPDATE and DELETE
• PostgreSQL slot readiness and retained-WAL Prometheus metrics
• SQLite checkpoint storage
• SQLite dead-letter storage
• SQLite delivered-envelope ledger storage
• webhook static headers, env-backed headers, and HMAC-SHA256 signing
• dead-letter inspection and filtered replay commands
• explicit extension registries for state, destination, and runtime adapters
• CDC-core processor results and observer-backed dispatch metrics
• node identity and local capability reporting
• lifecycle hooks, configuration providers, and reusable local command objects
• Docker image distribution
• Helm-based Kubernetes deployment

The supported compatibility boundaries for configuration, webhook payloads, CLI behavior, and operational-state migrations are documented in Compatibility. The canonical event and transaction JSON contracts are documented in Webhook Payloads.

Mammoth's logging.level accepts debug, info, warn, or error. Logs are newline-delimited JSON on standard output so Docker and Kubernetes collect them directly. info is the recommended default; use debug temporarily for per-work and WAL acknowledgement detail. See Configuration for the logged events and sensitive-data boundary.

v1 Non-goals

Mammoth 1.x does not provide:

• a web dashboard
• multiple active consumers for the same PostgreSQL replication slot
• DDL or sequence replication
• destination-side semantic conflict resolution
• a global exactly-once guarantee across independent operational-state stores

These are explicit product boundaries rather than indicators of pre-production status.