installArchiving() function

Install the row-archiving machinery: a mirror archive schema, its settings table, the sweep function, and — best effort — a pg_cron schedule to run it.

Signature:

export declare function installArchiving(options: InstallArchiveOptions): Promise<void>;

Parameters

Returns:

Promise<void>

Nothing; it resolves once the DDL has been applied.

Exceptions

Error when any schema, table or column name is not a plain SQL identifier — these are interpolated into DDL, so they are validated rather than escaped.

Remarks

Aged rows are moved out of the watched tables into same-named tables in the archive schema, which keeps the hot tables small without losing the data. Every step is idempotent, so this is safe to call on every start.

What it does, in order:

1. Creates the archive schema. 2. Creates its settings table, one row per watched table: the source schema, the watch column, the retention period in seconds, an enabled flag, and a hash of the config the code asked for. 3. Reconciles the supplied models against that table — inserting new rows, and rewriting the code-owned columns only when the hash differs. 4. Creates the run() sweep function. For each enabled setting it checks whether any row is older than that setting's period, and only then creates archive.<table> and moves the aged rows across in a single DELETE ... RETURNING piped into an INSERT. So the archive table appears when there is finally something to put in it, not at install time. 5. Tries to create the pg_cron extension and schedule run(). This step is best effort: if pg_cron is unavailable the failure is caught and scheduling is skipped without an error, which means a successful call does NOT guarantee the sweep is scheduled. run() is a plain function, so it can equally be called by hand or driven by any external scheduler.

The division of ownership in step 3 is the part worth understanding. While the hash is unchanged, an operator's edits to the source schema, watch column and period are preserved — the code will not clobber them on the next start. Changing any of those three in code changes the hash, and then the code's values win. The enabled flag is never written after the initial insert, so turning a table off in the database keeps it off regardless.

run() reads the settings table at call time rather than baking them in, so operator changes take effect on the next sweep without reinstalling.

Example

await installArchiving({
    client: prisma,
    models: [{ name: 'AuditLog', periodSeconds: 7 * 24 * 3600 }],
});

Read this page as plain markdown — no HTML, no navigation. For pasting into an LLM, or for an agent to fetch.