+Postgres version compatibility
+
+The table above uses PostgreSQL's built-in uuid functionality, which is available from version 14.
+For backwards compatibility you can use the uuid-ossp extension.
+
+
+create extension if not exists "uuid-ossp";
+
+
+
+
+
+### Query Patterns
+
+An audit log doesn't do us much good if its too slow to query! There are 2 query patterns we think are table stakes (😉) for an audit system:
+
+**Changes to a Table in a Time Range**
+
+For time slices, we need an index on the `ts` column. Since the table is append-only and the `ts` column is populated by insertion date, our values for `ts` are naturally in ascending order.
+
+PostgreSQL's builtin [BRIN index](https://www.postgresql.org/docs/current/brin-intro.html) can leverage that correlation between value and physical location to produce an index that, at scale, is many hundreds of times smaller than the default (BTREE index) with faster lookup times.
+
+```sql
+-- index ts for time range filtering
+create index record_version_ts
+ on audit.record_version
+ using brin(ts);
+```
+
+For table filtering, we've included a `table_oid` column which tracks PostgreSQL's internal `integer` identifier. We can add an index to this column instead of the `table_schema` and `table_name` columns, minimizing the index size and offering better performance.
+
+```sql
+-- index table_oid for table filtering
+create index record_version_table_oid
+ on audit.record_version
+ using btree(table_oid);
+```
+
+**Changes to a Record Over Time**
+
+One of the downsides to storing each row's data as `jsonb` is that filtering based on a column's value becomes very inefficient. If we want to look up a row's history quickly, we need to extract and index a unique identifier for each row.
+
+For the globally unique identifier, we'll use the following structure
+
+```
+[table_oid, primary_key_value_1, primary_key_value_2, ...]
+```
+
+and hash that array as a UUID v5 to get an efficiently indexable UUID type to identify the row that is robust to data changes.
+
+We'll use one utility function to lookup a record's primary key column names:
+
+```sql
+create or replace function audit.primary_key_columns(entity_oid oid)
+ returns text[]
+ stable
+ security definer
+ language sql
+as $$
+ -- Looks up the names of a table's primary key columns
+ select
+ coalesce(
+ array_agg(pa.attname::text order by pa.attnum),
+ array[]::text[]
+ ) column_names
+ from
+ pg_index pi
+ join pg_attribute pa
+ on pi.indrelid = pa.attrelid
+ and pa.attnum = any(pi.indkey)
+ where
+ indrelid = $1
+ and indisprimary
+$$;
+```
+
+and another to consume the `table_oid` and primary key, converting the result into the record's UUID.
+
+```sql
+create or replace function audit.to_record_id(
+ entity_oid oid,
+ pkey_cols text[],
+ rec jsonb
+)
+ returns uuid
+ stable
+ language sql
+as $$
+ select
+ case
+ when rec is null then null
+ -- if no primary key exists, use a random uuid
+ when pkey_cols = array[]::text[] then uuid_generate_v4()
+ else (
+ select
+ uuid_generate_v5(
+ 'fd62bc3d-8d6e-43c2-919c-802ba3762271',
+ (
+ jsonb_build_array(to_jsonb($1))
+ || jsonb_agg($3 ->> key_)
+ )::text
+ )
+ from
+ unnest($2) x(key_)
+ )
+ end
+$$;
+```
+
+Finally, we index the `record_id` and `old_record_id` columns that contain these unique identifiers for fast querying.
+
+```sql
+-- index record_id for fast searching
+create index record_version_record_id
+ on audit.record_version(record_id)
+ where record_id is not null;
+
+-- index old_record_id for fast searching
+create index record_version_old_record_id
+ on audit.record_version(record_id)
+ where old_record_id is not null;
+```
+
+### Enrollment
+
+Okay, so we have a home for our audit data that we're confident it can be queried efficiently. Now how do we populate it?
+
+We need the audit table to populate without end-users making any changes to their transactions. So we'll set up a [trigger](https://www.postgresql.org/docs/current/sql-createtrigger.html) to fire when the data changes. In this case, we'll fire the trigger once for every inserted/updated/deleted row.
+
+```sql
+create or replace function audit.insert_update_delete_trigger()
+ returns trigger
+ security definer
+ language plpgsql
+as $$
+declare
+ pkey_cols text[] = audit.primary_key_columns(TG_RELID);
+ record_jsonb jsonb = to_jsonb(new);
+ record_id uuid = audit.to_record_id(TG_RELID, pkey_cols, record_jsonb);
+ old_record_jsonb jsonb = to_jsonb(old);
+ old_record_id uuid = audit.to_record_id(TG_RELID, pkey_cols, old_record_jsonb);
+begin
+
+ insert into audit.record_version(
+ record_id,
+ old_record_id,
+ op,
+ table_oid,
+ table_schema,
+ table_name,
+ record,
+ old_record
+ )
+ select
+ record_id,
+ old_record_id,
+ TG_OP,
+ TG_RELID,
+ TG_TABLE_SCHEMA,
+ TG_TABLE_NAME,
+ record_jsonb,
+ old_record_jsonb;
+
+ return coalesce(new, old);
+end;
+$$;
+```
+
+## Public API
+
+Finally, we'll wrap up the trigger creation and removal process behind a clean, idempotent, user facing API.
+
+The API we'll expose for enabling auditing on a table is
+
+```sql
+select audit.enable_tracking('