decoderbufs
Protocol Buffers WAL decoder for Debezium — a faithful servant, if one whose duties have been largely assumed by the household.
I should be candid from the outset: decoderbufs is a PostgreSQL logical decoding output plugin that has been largely superseded by pgoutput for new deployments. It encodes write-ahead log (WAL) changes as Protocol Buffers, was built specifically for Debezium, and produces a compact binary message for each row-level change in the database. It served its purpose admirably. One simply ought to know that the household now has a built-in alternative.
What decoderbufs does
PostgreSQL's logical decoding infrastructure reads the WAL and converts physical changes into a logical stream of row-level events — inserts, updates, and deletes. An output plugin determines how those events are serialized. decoderbufs serializes them as Protocol Buffers (protobuf), a compact binary format originally developed by Google.
When a consumer (typically a Debezium connector) attaches to a logical replication slot that uses decoderbufs, PostgreSQL decodes each committed transaction and passes the changes through the plugin. decoderbufs converts each change into a protobuf message containing the table name, the operation type, and the column values — both old and new — then sends it to the consumer over the replication protocol.
The protobuf format is smaller and faster to parse than text-based alternatives like JSON, which matters at high change volumes. However, it requires the protobuf-c library to be installed on the PostgreSQL server and the consumer to understand the protobuf schema. A trade-off worth understanding before you commit to it.
When to use decoderbufs
decoderbufs is narrowly scoped. It exists for one primary use case:
- Debezium CDC pipelines on self-hosted PostgreSQL — if you are running Debezium against a PostgreSQL server you control and your deployment predates Debezium 2.x, you may already be using decoderbufs
For new installations, Debezium recommends pgoutput — PostgreSQL's built-in logical replication protocol, available since PostgreSQL 10. pgoutput requires no additional plugin installation, works on all managed cloud databases, and is maintained by the PostgreSQL community rather than the Debezium project.
decoderbufs remains supported in current Debezium releases, but it is no longer the default and there is no technical advantage over pgoutput for most deployments.
Installation and setup
decoderbufs must be compiled from source and installed into the PostgreSQL server's library directory. It requires the protobuf-c development library and PostgreSQL server development headers — not a casual afternoon, but manageable if you've built extensions before.
# Install build dependencies (Debian/Ubuntu)
sudo apt-get install build-essential pkg-config \
postgresql-server-dev-16 libprotobuf-c-dev
# Clone and build
git clone https://github.com/debezium/postgres-decoderbufs.git
cd postgres-decoderbufs
make && sudo make installAfter building, configure PostgreSQL to load the plugin and enable logical decoding.
# postgresql.conf — requires a restart after changes
shared_preload_libraries = 'decoderbufs'
wal_level = logical
max_replication_slots = 4
max_wal_senders = 4A PostgreSQL restart is required after changing these settings. Once the server is back up, you can create a logical replication slot that uses decoderbufs.
-- Create a logical replication slot using decoderbufs
SELECT pg_create_logical_replication_slot('debezium_slot', 'decoderbufs');Consuming changes
In practice, you rarely interact with the replication slot directly — Debezium manages the slot and consumes changes automatically. For testing and debugging, PostgreSQL provides built-in functions to peek at or consume decoded changes.
-- Peek at decoded changes (does not consume them)
SELECT * FROM pg_logical_slot_peek_changes('debezium_slot', NULL, NULL);
-- Consume changes (advances the slot position)
SELECT * FROM pg_logical_slot_get_changes('debezium_slot', NULL, NULL);When the CDC pipeline is decommissioned, drop the replication slot to stop WAL retention.
-- Drop the replication slot when no longer needed
SELECT pg_drop_replication_slot('debezium_slot');Leaving an unconsumed replication slot active will cause WAL to accumulate indefinitely, eventually filling the disk. I have seen this particular oversight fill a 500GB volume over a long weekend. Always monitor slot lag in production.
Cloud availability
| Provider | Status |
|---|---|
| Amazon RDS / Aurora | Not available — use pgoutput or wal2json |
| Google Cloud SQL | Not available — use pgoutput or wal2json |
| Azure Database for PostgreSQL | Not available — use pgoutput or wal2json |
| Supabase | Not available — use pgoutput |
| Neon | Not available — use pgoutput |
decoderbufs requires installing a custom shared library on the PostgreSQL server, which managed services do not permit. All major cloud providers support pgoutput, which Debezium works with natively. If I may be direct: this table is the reason Debezium shifted its default from decoderbufs to pgoutput.
How Gold Lapel relates
I will be straightforward: Gold Lapel and decoderbufs occupy different rooms of the household entirely. Gold Lapel optimizes how your queries read data — automatic materialized views, index recommendations, proxy-level analysis. CDC concerns itself with capturing changes for downstream consumers. Different duties, no overlap.
The two coexist on the same database without conflict. Gold Lapel does not interact with logical replication slots or WAL decoding, and has no reason to.