Updated at July 17, 2026 02:08 PM

WAL extensions

WAL extensions allow you to add auxiliary information to each write-ahead log record. For example, you can enable storing an old and new tuple for each CRUD operation performed. This information might be helpful for implementing a CDC (Change Data Capture) utility that transforms a data replication stream.

Configuration

WAL extensions are disabled by default. To configure them, use the wal.ext.* configuration options. Inside the wal.ext block, you can enable storing old and new tuples as follows:

To store old and new tuples in a write-ahead log for all spaces, set the wal.ext.old and wal.ext.new options to true:


ext:  new: true  old: true

To adjust these options for specific spaces, specify the wal.ext.spaces option:


wal:  ext:    old: true    new: true    spaces:      space1:        old: false      space2:        new: false

The configuration for specific spaces has priority over the configuration in the wal.ext.new and wal.ext.old options. It means that only new tuples are added to the log for space1 and only old tuples for space2.

Note that records with additional fields are replicated as follows:

If a replica doesn't support the extended format configured on a master, auxiliary fields are skipped.
If a replica and master have different configurations for WAL records, the master's configuration is ignored.

Example

The table below demonstrates how write-ahead log records might look for the specific CRUD operations if storing old and new tuples is enabled for the bands space.

Operation	Example	WAL information
insert	`bands:insert{4, 'The Beatles', 1960}`	\| new_tuple: [4, 'The Beatles', 1960] \| tuple: [4, 'The Beatles', 1960]
delete	`bands:delete{4}`	\| key: [4] \| old_tuple: [4, 'The Beatles', 1960]
update	`bands:update({2}, {{'=', 2, 'Pink Floyd'}})`	\| new_tuple: [2, 'Pink Floyd', 1965] \| old_tuple: [2, 'Scorpions', 1965] \| key: [2] \| tuple: [['=', 2, 'Pink Floyd']]
upsert	`bands:upsert({2, 'Pink Floyd', 1965}, {{'=', 2, 'The Doors'}})`	\| new_tuple: [2, 'The Doors', 1965] \| old_tuple: [2, 'Pink Floyd', 1965] \| operations: [['=', 2, 'The Doors']] \| tuple: [2, 'Pink Floyd', 1965]
replace	`bands:replace{1, 'The Beatles', 1960}`	\| old_tuple: [1, 'Roxette', 1986] \| new_tuple: [1, 'The Beatles', 1960] \| tuple: [1, 'The Beatles', 1960]

Operation

Example

WAL information

insert

bands:insert{4, 'The Beatles', 1960}

| new_tuple: [4, 'The Beatles', 1960] | tuple: [4, 'The Beatles', 1960]

delete

bands:delete{4}

| key: [4] | old_tuple: [4, 'The Beatles', 1960]

update

bands:update({2}, {{'=', 2, 'Pink Floyd'}})

| new_tuple: [2, 'Pink Floyd', 1965] | old_tuple: [2, 'Scorpions', 1965] | key: [2] | tuple: [['=', 2, 'Pink Floyd']]

upsert

bands:upsert({2, 'Pink Floyd', 1965}, {{'=', 2, 'The Doors'}})

| new_tuple: [2, 'The Doors', 1965] | old_tuple: [2, 'Pink Floyd', 1965] | operations: [['=', 2, 'The Doors']] | tuple: [2, 'Pink Floyd', 1965]

replace

bands:replace{1, 'The Beatles', 1960}

| old_tuple: [1, 'Roxette', 1986] | new_tuple: [1, 'The Beatles', 1960] | tuple: [1, 'The Beatles', 1960]

Storing both old and new tuples is especially useful for the update operation because a write-ahead log record contains only a key value.

Was this article helpful?

Table of Contents
Configuration
Example
Was this article helpful?