Skip to content

pg_vault_tables Documentation

Extension File Structure

Extension file structure¶

Installed files¶

File	Location
`pg_vault_tables.so`	`$(pg_config --pkglibdir)`
`pg_vault_tables.control`	`$(pg_config --sharedir)/extension`
`pg_vault_tables--0.1.sql`	`$(pg_config --sharedir)/extension`

Source layout¶

pg_vault_tables/
├── pg_vault_tables.control
├── Makefile
├── src/
│   ├── vault_tableam.c          the access method routine and its callbacks
│   ├── vault_enforce.c          permission, retention and insert-once decisions
│   ├── vault_reloptions.c       option parsing and catalogue storage
│   ├── vault_utility_hook.c     ProcessUtility: creation and ALTER TABLE
│   ├── vault_object_access.c    object_access: DROP and TRUNCATE
│   ├── vault_violation.c        the violation record
│   └── vault_options_accessor.c the SQL-callable options accessor
├── sql/
│   └── pg_vault_tables--0.1.sql
├── test/
│   ├── sql/                     pg_regress inputs
│   ├── expected/                pg_regress expected output
│   └── specs/                   isolation specifications
├── t/                           TAP tests
└── docs/                        this site

SQL objects created¶

All in the pgvault_tables schema, except the access method.

Object	Kind	Notes
`vault`	access method	Not schema-scoped; lives in `pg_am`
`vault_tableam_handler(internal)`	function	Named by `CREATE ACCESS METHOD`
`pgvault_tables`	schema	`USAGE` granted to `PUBLIC`
`_table_options(regclass)`	function	Internal accessor; owner only
`vault_tables`	view	Internal; owner only
`view_vault_tables()`	function	The public registry call; `SECURITY DEFINER`
`purge_vault(name, name)`	procedure	Owner only; deletes rows

Why `pgvault_tables` and not `vault`¶

Supabase's own vault extension installs into a schema literally named vault on every Supabase project. Using the bare name would be a genuine installation conflict, not a style preference.

The access method itself keeps the name vault, because access methods live in pg_am — a separate namespace — and are conventionally named for what they do rather than which package installed them, as heap, btree and gin are.

Test suites¶

Suite	Harness	Covers
`vault_scaffold`	pg_regress	Delegation to heap
`vault_transparency`	pg_regress	Ordinary PostgreSQL is unaffected
`vault_reloptions`	pg_regress	Option parsing and storage
`vault_enforcement`	pg_regress	Row-level enforcement
`vault_statement`	pg_regress	`ALTER`, `DROP`, `TRUNCATE`, cascades
`vault_purge`	pg_regress	Registry and purge procedure
`vault_matrix`	pg_regress	Every refusal, as three different roles
`vault_maintenance`	pg_regress	Vacuum, indexes, triggers
`insertonce`	isolation	Concurrent first insert
`001_dump_restore`	TAP	Dump and restore round trip
`002_fail_closed`	TAP	Behaviour without the library loaded
`003_replication`	TAP	Physical replication
`004_logical_replication`	TAP	Logical replication
`005_violations`	TAP	Violation record completeness

All are run by make installcheck, which invokes all three harnesses in one target — pg_regress, then pg_isolation_regress, then prove. PGXS has no separate installcheck-isolation or installcheck-tap targets.

The whole of it runs on every platform in the matrix: PostgreSQL 16, 17 and 18, across Rocky Linux 8 and 9, Debian 12, Ubuntu 22.04, 24.04 and 26.04 LTS, and Fedora 44. See Version and platform coverage and Tested Platforms.