Glossary¶
Terms used throughout this documentation, in plain English. If you are new to PostgreSQL or to pg_auto_mv, read this page first — the rest of the documentation assumes these words.
auto_mv_id¶
The UUID pg_auto_mv assigns to each registered view. It is the identifier used everywhere: in the audit tables, in the queue payload, and in the names of the triggers pg_auto_mv creates. You get it back from register_mv(), and you can look it up any time with get_mv().
In a multi-master cluster you deliberately supply the same auto_mv_id on every node, so one view has one identity across the whole cluster.
chain¶
A link that says "when view A finishes refreshing, refresh view B next". Used when B is built from A, so refreshing them in the wrong order would leave B built from stale data. See Chaining materialised views.
concurrent refresh¶
REFRESH MATERIALIZED VIEW CONCURRENTLY — a refresh that lets people keep reading the view while it rebuilds. PostgreSQL requires the view to have a unique index and to already be populated. pg_auto_mv uses it by default.
If the view has no unique index, registration fails and tells you so. If the view exists but has never been populated, pg_auto_mv quietly does a plain (non-concurrent) refresh that one time, because a concurrent refresh is impossible on an empty view.
cooldown¶
The minimum number of seconds between the end of one refresh and the start of the next. Stops an expensive view being refreshed back-to-back. One of the three timing parameters.
dispatch¶
The moment pg_relay picks a queued request off the queue and runs it. "Dispatched" means the request has been handed to the code that does the actual refresh.
event¶
A single recorded change on a watch table. Each trigger firing writes one row to pgauto_mv.mv_events. Events are the raw audit trail — they record that something happened, not that a refresh ran.
materialised view (MV)¶
A PostgreSQL object that stores the result of a query on disk, rather than re-running the query every time (which is what a plain VIEW does). Fast to read, but goes stale when the underlying data changes. Refreshing it re-runs the query and replaces the stored result.
max_wait¶
The maximum number of seconds pg_auto_mv will wait from the first change before forcing a refresh, no matter how much activity keeps arriving. Stops a constantly busy table from postponing a refresh forever. 0 means no cap. One of the three timing parameters.
mv_state / mv_state_v¶
mv_state is the table holding raw operational state for each view: is a refresh pending, when did the first and last change arrive, when did the last refresh finish. It stores facts only.
mv_state_v is a view over it that calculates the derived timings — when the refresh is actually due, when the cooldown expires. All of pg_auto_mv's own code reads the view, never the raw table, so there is exactly one place the timing arithmetic lives.
node-local¶
A table whose contents are meaningful only on the database server it lives on, and which must therefore not be copied to other servers by replication. Most pg_auto_mv tables are node-local, because each server has its own physical copy of each materialised view and its own refresh history. See Replication and standbys.
pending¶
The state between "something changed" and "the refresh has run". While a view is pending, further changes update the timing but do not queue extra refreshes — they all collapse into the one refresh that is coming.
pg_relay¶
The companion extension pg_auto_mv is built on. It provides the durable queue, and a small background program (the Processor) that polls that queue once a second and runs whatever each entry says to run. pg_auto_mv writes entries; pg_relay executes them.
pg_auto_mv cannot work without it. Documentation: https://pg-relay.pebbleit.com.au/
pgrelay.schedule¶
pg_relay's shared type for describing a recurring schedule — "weekdays at 04:30", "Monday at 05:00 and Tuesday at 17:30". pg_auto_mv uses it rather than inventing its own, so the same schedule syntax works across every pg_relay-based tool.
It is not part of the pg_relay extension and is installed as a separate step. See Installation.
private schedule / shared schedule¶
A shared schedule is created by name and attached to as many views as you like — change it once, and every attached view follows the new timing.
A private schedule belongs to exactly one view, is created automatically when you pass schedule settings directly to register_mv(), and is deleted when that view is unregistered.
refresh_lag¶
How many seconds of quiet pg_auto_mv waits after the most recent change before refreshing. If changes keep arriving, the wait keeps restarting — so a burst of activity produces one refresh at the end, not one per change. One of the three timing parameters.
refresh_source¶
Why the current pending refresh exists: event (a watch table changed), chain (an upstream view finished refreshing), or direct (somebody called refresh_materialised_view_now()).
registration¶
Telling pg_auto_mv to manage an existing materialised view, via register_mv(). Registration creates the triggers and the catalog rows. It does not create the view — that is your job, with ordinary DDL.
schedule¶
A time-based refresh, independent of whether any data changed. Two kinds: interval (every N hours/minutes) and time (specific times on specific days, always UTC). See Scheduling.
skip_reason¶
Recorded in the refresh log when a scheduled slot came around but the refresh did not run — because the view was paused, the view no longer exists, it was still in cooldown, or a refresh was already running. A skip is logged rather than silently dropped, so you can see it happened.
standby¶
A read-only copy of a database kept in sync by streaming replication. Materialised views are copied to standbys automatically as part of that stream, so pg_auto_mv deliberately does nothing on a standby. If the standby is promoted to primary, pg_auto_mv starts working there with no intervention.
sync (sync_mv)¶
A maintenance job that reconciles pg_auto_mv's catalog against the database's real state — noticing views that have been renamed, moved to another schema, or dropped. Runs daily by default.
trigger¶
A small function PostgreSQL runs automatically when a table changes. pg_auto_mv generates one per watched table. It is deliberately tiny: record the event, update the state, queue a request, done. It never refreshes the view itself.
unregister¶
Removing pg_auto_mv's management of a view: drops the triggers and the catalog rows. It does not drop the materialised view itself, which continues to exist exactly as before — just without automatic refreshing.
watch table¶
A table pg_auto_mv monitors for changes on behalf of a view. When it changes, the view is scheduled for refresh. A view can have many watch tables, or none at all (if you drive it purely by schedule, chain, or on demand).