Glossary

Terms used throughout this documentation.

---

Access method : The PostgreSQL component that actually stores and retrieves a table's rows. The built-in one is called heap. This extension supplies one called vault, which uses heap for the storage and adds the permission checks.

Append-only : A table that can be added to but never changed or removed from. In this extension, permissions = 'insert'.

Cascade : When dropping or truncating one object automatically affects others — DROP SCHEMA x CASCADE removing everything in the schema, for instance. Cascades are the reason enforcement cannot live only at the statement level.

Fail closed : Denying an operation whenever the answer is uncertain, rather than allowing it. If this extension cannot work out what a table permits, it permits nothing.

Insert-once : permissions = 'insertonce'. The first insert into the empty table succeeds; every later one fails for the life of the table.

Isolation level : How much of other transactions' work a transaction can see. Relevant here because retention is enforced identically at every isolation level.

MVCC : Multi-Version Concurrency Control — how PostgreSQL lets readers and writers work at the same time by keeping multiple versions of a row. Vault tables use PostgreSQL's ordinary implementation.

Permissions : In this extension specifically, the fixed list of operations a vault table allows, set when it is created. Not the same as PostgreSQL's GRANT permissions, which continue to work as normal alongside it.

Preload : Listing a library in shared_preload_libraries so PostgreSQL loads it at startup. Compulsory for this extension, on every server.

Purge : Removing rows whose retention deadline has passed, using pgvault_tables.purge_vault().

Reloption : A per-table setting, written as WITH (name = value) on CREATE TABLE. permissions and retention are stored alongside PostgreSQL's own reloptions.

Retention : A minimum number of days a row must be kept before it may be deleted. Optional, set at creation, and unchangeable afterwards.

Standby : A replica server that receives changes from a primary. Standbys need this extension preloaded too, even though replication itself does not involve it.

Superuser : A PostgreSQL role that bypasses ordinary permission checks. It does not bypass this extension.

TOAST : How PostgreSQL stores values too large for a single page. Handled entirely by heap; vault tables need no special treatment for it.

Vault table : A table created with USING vault, which enforces its declared permissions against every role.

Violation record : A line written to the PostgreSQL log each time an operation is refused, so somebody other than the person who attempted it can see it happened.

_$purge_ts : The column added to a table that sets retention. It holds the moment each row becomes eligible for deletion — the deadline, not the arrival time.