provsql_rmgr.c File Reference

WAL-logging the circuit store through a custom resource manager. More...

#include "postgres.h"
#include "provsql_config.h"
#include "provsql_rmgr.h"

Include dependency graph for provsql_rmgr.c:

Go to the source code of this file.

Functions
void	provsql_register_rmgr (void)
	Register ProvSQL's resource manager with PostgreSQL.
void	provsql_wal_log_store_message (const char *data, size_t len)
	Write one store message to the WAL, if WAL logging is on.
bool	provsql_store_write_allowed (void)
	Whether this process may write to the circuit store.

Variables
bool	provsql_wal_logging = false
	Global variable set by the provsql.wal_logging run-time configuration parameter: when true, every mutation of the circuit store is written to the WAL before it is written to the store.

Detailed Description

WAL-logging the circuit store through a custom resource manager.

The circuit store is not a set of relations, so PostgreSQL's own machinery does not carry it: it is invisible to crash recovery, streaming replication and PITR. From PostgreSQL 15 an extension can register a resource manager of its own and write WAL records the startup process will replay, which is the one mechanism that brings a non-relation file under WAL without putting it in shared buffers.

The design is the one the store's shape makes natural. Every mutation is already a self-describing message – opcode, database, payload – so a record is just that message, and replay is feeding it back to the worker. Records are not tied to the commit: like an index page split they are applied whether or not the transaction commits, which is exactly the semantics gate creation already has, and replay is idempotent because creating a gate that exists is a no-op and writing a probability a gate already holds is a no-op too.

What it is for. Streaming replication and PITR: a standby's startup process applies these records to its own store, so a replica can carry provenance. Crash recovery does not depend on them, and that is deliberate: provsql.wal_logging requires provsql.synchronous_commit, so a transaction cannot commit until its store writes are on disk, and the store on disk is therefore never behind the WAL. That requirement is what removes the checkpoint gap an asynchronous store would open – WAL before the last checkpoint's redo pointer is recycled, so a store that lagged across a whole checkpoint could not be repaired by replay.

What it is not. A hot-standby backend must not write to the store, so provenance queries on a standby only work for gates that already exist there – and almost every provenance query creates gates, reads included. Making them work needs a session-local overlay store, which is a different piece of work.

Off by default: it changes what a cluster writes to its WAL, and a replica that has never seen these records is better off without them.

Definition in file provsql_rmgr.c.

Function Documentation

provsql_register_rmgr()

void provsql_register_rmgr

(

void

)

Register ProvSQL's resource manager with PostgreSQL.

Must be called from _PG_init under shared_preload_libraries, and is called unconditionally – registration is what lets any WAL that already contains ProvSQL records be replayed, whether or not this cluster is currently writing them. A no-op before PostgreSQL 15.

Definition at line 184 of file provsql_rmgr.c.

Here is the caller graph for this function:

provsql_store_write_allowed()

bool provsql_store_write_allowed

(

void

)

Whether this process may write to the circuit store.

False in a hot-standby backend: the standby's store is maintained by replay, and a backend writing to it would make the two diverge for good. True in the startup process while it replays a ProvSQL record, which is the one write recovery is supposed to make.

Definition at line 192 of file provsql_rmgr.c.

Here is the caller graph for this function:

provsql_wal_log_store_message()

void provsql_wal_log_store_message	(	const char *	data,
		size_t	len )

Write one store message to the WAL, if WAL logging is on.

Parameters

data	The complete message, starting with its opcode byte.
len	Its length in bytes.

Definition at line 186 of file provsql_rmgr.c.

Here is the caller graph for this function:

Variable Documentation

provsql_wal_logging

bool provsql_wal_logging = false

Global variable set by the provsql.wal_logging run-time configuration parameter: when true, every mutation of the circuit store is written to the WAL before it is written to the store.

Definition at line 182 of file provsql_rmgr.c.